@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
@@ -5,11 +5,13 @@ import {
5
5
  extractFullManagedBlock,
6
6
  extractManagedBlock,
7
7
  findLineAnchoredMarkers,
8
+ findUnmarkedCopy,
8
9
  selectMarkers,
9
10
  type MarkerStyle,
10
11
  } from "./managed-block.js";
11
12
  import { readTemplate } from "../render/parts.js";
12
13
  import { applyTokens, type TokenMap } from "./placeholders.js";
14
+ import { sha256 } from "./version-file.js";
13
15
 
14
16
  // ---------------------------------------------------------------------------
15
17
  // JsonValue — generic JSON type used throughout Tier-2 JSON helpers
@@ -202,7 +204,7 @@ export function deepMergeJson(base: JsonValue, override: JsonValue): JsonValue {
202
204
  // - dest present, valid JSON, template contained → no-op (idempotent)
203
205
  // - dest present, valid JSON, containment fails → deepMergeJson(existing, template)
204
206
  // (template wins on key collisions; consumer-only keys outside template tree preserved)
205
- // - dest present, malformed JSON → overwrite with template
207
+ // - dest present, malformed JSON → throw; the consumer fixes it by hand
206
208
  // - schemaFlipped: true when a path value changed type during deep-merge
207
209
  // ---------------------------------------------------------------------------
208
210
 
@@ -309,11 +311,58 @@ export function writeTier1(
309
311
  // - dest absent → write whole file (with token substitution)
310
312
  // - dest has markers → update only the bkit block (tokens applied to new block content)
311
313
  // - dest present, no marks → append full block at EOF; preserve consumer content above
314
+ // - no marks, markdown dest already holds an unmarked copy of the block (findUnmarkedCopy)
315
+ // → warn + skip; appending would leave a frozen duplicate above it
312
316
  //
313
317
  // markerStyle: "html-comment" for markdown, shell and `.gitignore` (`# ` prefix allowed);
314
318
  // "slash-comment" for JS.
315
319
  // ---------------------------------------------------------------------------
316
320
 
321
+ /**
322
+ * sha256 of the driver (everything outside the managed block) of hook files a bkit
323
+ * release shipped with a host contract the host does not accept, keyed by consumer path.
324
+ * Register: docs/migrations.md.
325
+ */
326
+ export const RETIRED_DRIVER_HASHES: Readonly<Record<string, readonly string[]>> = {
327
+ // 5.1.0: Claude-shaped `hookSpecificOutput`; Antigravity reads `{ decision, reason }`.
328
+ ".agents/plugins/bkit/hooks/bkit-gateguard.cjs": [
329
+ "544dbcc2bab81875789563a2925bb5dc7b5dbbcf185f216fb3281cfa01ec030d",
330
+ ],
331
+ ".agents/plugins/bkit/hooks/bkit-guardrails.cjs": [
332
+ "8e5d75f7e1a4527889dafa6a250ae370e2acf1b5fc7d58929dfc759489746e14",
333
+ ],
334
+ };
335
+
336
+ /** The text outside a file's single managed block, or null without exactly one block. */
337
+ export function driverText(content: string, markerStyle: MarkerStyle): string | null {
338
+ const [startMarker, endMarker] = selectMarkers(markerStyle);
339
+ const starts = findLineAnchoredMarkers(content, startMarker);
340
+ const ends = findLineAnchoredMarkers(content, endMarker);
341
+ if (starts.length !== 1 || ends.length !== 1 || ends[0]! < starts[0]!) return null;
342
+ return content.slice(0, starts[0]) + content.slice(ends[0]);
343
+ }
344
+
345
+ /**
346
+ * True when `dstPath` still carries a retired bkit driver the consumer never edited. An
347
+ * edited driver still on the retired output shape is kept and gets a printed fix.
348
+ */
349
+ function hasRetiredDriver(dstPath: string, content: string, markerStyle: MarkerStyle): boolean {
350
+ const posix = dstPath.replace(/\\/g, "/");
351
+ const key = Object.keys(RETIRED_DRIVER_HASHES).find(
352
+ (rel) => posix === rel || posix.endsWith(`/${rel}`),
353
+ );
354
+ if (key === undefined) return false;
355
+ const driver = driverText(content, markerStyle);
356
+ if (driver === null) return false;
357
+ if (RETIRED_DRIVER_HASHES[key]!.includes(sha256(driver))) return true;
358
+ if (driver.includes("hookSpecificOutput")) {
359
+ console.warn(
360
+ `[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.`,
361
+ );
362
+ }
363
+ return false;
364
+ }
365
+
317
366
  export function writeTier2(
318
367
  srcPath: string,
319
368
  dstPath: string,
@@ -324,6 +373,17 @@ export function writeTier2(
324
373
  ): void {
325
374
  const srcRaw = readTemplate(srcPath);
326
375
 
376
+ // A retired, unedited bkit driver is bkit's code, not the consumer's: replace the
377
+ // whole file so the new driver ships with the new block.
378
+ if (
379
+ fs.existsSync(dstPath) &&
380
+ hasRetiredDriver(dstPath, fs.readFileSync(dstPath, "utf-8"), markerStyle)
381
+ ) {
382
+ if (!dryRun) fs.writeFileSync(dstPath, applyTokens(srcRaw, tokens), "utf-8");
383
+ ws.writes.push({ path: dstPath, action: "write" });
384
+ return;
385
+ }
386
+
327
387
  if (!fs.existsSync(dstPath)) {
328
388
  // dest missing → write whole template (with tokens applied)
329
389
  const content = applyTokens(srcRaw, tokens);
@@ -364,6 +424,13 @@ export function writeTier2(
364
424
 
365
425
  // dest has no markers → append full block at EOF (with tokens applied)
366
426
  const appliedBlock = applyTokens(fullBlock, tokens);
427
+ const copyTitle = dstPath.endsWith(".md") ? findUnmarkedCopy(destContent, appliedBlock) : null;
428
+ if (copyTitle !== null) {
429
+ console.warn(
430
+ `[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 -->\`.`,
431
+ );
432
+ return;
433
+ }
367
434
  const sep =
368
435
  destContent.length === 0
369
436
  ? ""
@@ -391,8 +391,6 @@ export interface OutcomePayload {
391
391
  frictionAdded?: number;
392
392
  deferralsAdded?: number;
393
393
  failuresAdded?: number;
394
- /** Sweep verdict from ship deferred-sweep step. */
395
- sweepVerdict?: string;
396
394
  /**
397
395
  * `"brief"` = the run had no `{FID}-plan*.md` and worked from its input file
398
396
  * (build / ship `workflow-meta` row). Absent = the run had a plan. Brief runs
@@ -45,16 +45,15 @@ export function getPkgRoot(): string {
45
45
  }
46
46
 
47
47
  // ---------------------------------------------------------------------------
48
- // The three payload roots. Each folder carries one licence and one install
49
- // behaviour; a file's path inside its folder is where it lands in the consumer
50
- // repo.
48
+ // The three payload roots. Each folder carries one install behaviour; a file's
49
+ // path inside its folder is where it lands in the consumer repo.
51
50
  //
52
- // core/ PolyForm. Written and kept current. engine/, workflows/,
53
- // prompts/, .bkit/, hooks/ and every LICENSE.md are skipped
54
- // by install; the rest is copied at its folder-relative path.
55
- // shared/ MIT-0. Written and kept current: bkit's blocks and keys inside
51
+ // core/ Written and kept current. engine/, workflows/, prompts/,
52
+ // .bkit/ and hooks/ are skipped by install; the rest is copied
53
+ // at its folder-relative path.
54
+ // shared/ Written and kept current: bkit's blocks and keys inside
56
55
  // files the consumer also edits, plus small whole files.
57
- // templates/ MIT-0. Copy-and-own only: never applied to the repo, copied raw
56
+ // templates/ Copy-and-own only: never applied to the repo, copied raw
58
57
  // into the consumer's `.bkit/templates/` by syncTemplateCopies.
59
58
  // ---------------------------------------------------------------------------
60
59
 
@@ -109,10 +108,9 @@ export function templateRelPath(dest: string): string {
109
108
  /**
110
109
  * The absolute source path backing a consumer-relative dest, or `null` when no
111
110
  * payload root carries it. Checks `shared/` then `core/`, applying the dotfile
112
- * remap. Root-level `LICENSE.md` files are never install sources.
111
+ * remap.
113
112
  */
114
113
  export function findTemplateSource(relPath: string): string | null {
115
- if (path.basename(relPath) === "LICENSE.md") return null;
116
114
  const rel = templateRelPath(relPath);
117
115
  for (const root of [getSharedRoot(), getCoreRoot()]) {
118
116
  const p = path.join(root, rel);
@@ -0,0 +1,67 @@
1
+ // --- Antigravity hook contract: identical in bkit's three Antigravity hooks (bkit renders
2
+ // it from one source). Needs `fs`, `os` and `path` in scope; the host's own code above
3
+ // declares them.
4
+ //
5
+ // Live-verified on the agy CLI: PreToolUse stdin is `{ conversationId, toolCall: { name,
6
+ // args }, workspacePaths, stepIdx, ... }` — no tool_name / tool_input / session_id / cwd.
7
+ // Args: `view_file` AbsolutePath / StartLine / EndLine; `run_command` CommandLine / Cwd;
8
+ // `write_to_file` / `replace_file_content` TargetFile. Stdout is `{ decision, reason }`,
9
+ // and only a `deny`'s reason reaches the model.
10
+
11
+ /**
12
+ * Antigravity's envelope in the Claude-family shape bkit's shared engines read. A payload
13
+ * already in that shape (a consumer's own matcher, a test) passes through unchanged.
14
+ */
15
+ function fromAntigravityPayload(payload) {
16
+ if (!payload || typeof payload !== "object" || !payload.toolCall) return payload;
17
+ const args =
18
+ payload.toolCall.args && typeof payload.toolCall.args === "object" ? payload.toolCall.args : {};
19
+ const roots = payload.workspacePaths;
20
+ const root = Array.isArray(roots) && typeof roots[0] === "string" ? roots[0] : undefined;
21
+ return {
22
+ tool_name: payload.toolCall.name,
23
+ tool_input: args,
24
+ session_id: payload.conversationId,
25
+ cwd: typeof args.Cwd === "string" ? args.Cwd : root,
26
+ };
27
+ }
28
+
29
+ // Model-written labels that differ between two otherwise identical calls.
30
+ const AG_LABEL_ARGS = new Set(["toolAction", "toolSummary", "Description", "Instruction"]);
31
+
32
+ /** The call's identity: tool name plus its arguments, labels dropped, keys sorted. */
33
+ function agCallSignature(toolName, input) {
34
+ const args = input && typeof input === "object" ? input : {};
35
+ const kept = Object.keys(args)
36
+ .filter((k) => !AG_LABEL_ARGS.has(k))
37
+ .sort()
38
+ .map((k) => [k, args[k]]);
39
+ return JSON.stringify([toolName, kept]);
40
+ }
41
+
42
+ // One record per (hook, conversation): two hooks on the same call each let its retry through.
43
+ function agRetryFile(hook, sessionId) {
44
+ const safe =
45
+ typeof sessionId === "string" ? sessionId.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 128) : "";
46
+ return path.join(os.tmpdir(), "bkit-antigravity-retry", `${hook}.${safe || "no-session"}.json`);
47
+ }
48
+
49
+ /**
50
+ * Delivers an advisory the only way Antigravity shows one to the model: deny the call
51
+ * with the advisory as the reason, once. The identical call right after is the agent's
52
+ * retry and is allowed.
53
+ */
54
+ function adviseOnce(hook, sessionId, signature, advisory) {
55
+ const file = agRetryFile(hook, sessionId);
56
+ const last = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
57
+ if (last === signature) {
58
+ fs.rmSync(file, { force: true });
59
+ return { decision: "allow" };
60
+ }
61
+ fs.mkdirSync(path.dirname(file), { recursive: true });
62
+ fs.writeFileSync(file, signature, "utf-8");
63
+ return {
64
+ decision: "deny",
65
+ reason: `${advisory}\nBlocked once so you see this; repeat the same call to proceed.`,
66
+ };
67
+ }
@@ -4,9 +4,9 @@ const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit"]);
4
4
 
5
5
  // Pure: takes the already-parsed hook payload, returns the advisory to emit or
6
6
  // null. Never touches process.stdin / process.stdout — the driver below owns both.
7
- // Subagents are NOT exempt: dedup is per (session, file) and a subagent carries its
8
- // own session id, so it gets the checklist once for a file the orchestrator already
9
- // touched.
7
+ // Subagents are NOT exempt: dedup is per (session, agent, file). A Claude Code subagent
8
+ // shares its parent's session_id and carries its own agent_id, so it gets the checklist
9
+ // once for a file the orchestrator already touched.
10
10
  function bkitGateguard(payload) {
11
11
  if (!EDIT_TOOLS.has(payload.tool_name)) return null;
12
12
  const input = payload.tool_input || {};
@@ -14,5 +14,5 @@ function bkitGateguard(payload) {
14
14
  // A Write to a not-yet-existing path is a NEW file and gets the reuse checklist.
15
15
  const isNewFile =
16
16
  payload.tool_name === "Write" && typeof filePath === "string" && !fs.existsSync(filePath);
17
- return firstTouchAdvice(filePath, payload.session_id, isNewFile);
17
+ return firstTouchAdvice(filePath, dedupKey(payload.session_id, payload.agent_id), isNewFile);
18
18
  }
@@ -3,12 +3,14 @@
3
3
 
4
4
  // Basename patterns for quality-gate configs (lint / format / types / test / slop).
5
5
  // A matching path gets the gate-config advisory instead of the first-touch checklist.
6
- // JS / TS first, then the other ecosystems' gate configs (Python, Go, Rust).
6
+ // JS / TS first, then the other ecosystems' gate configs (Python, Go, Rust). Mixed-purpose
7
+ // manifests that also hold dependencies and metadata (package.json, pyproject.toml,
8
+ // setup.cfg, tox.ini) are not matched: routine edits to them are not gate edits.
7
9
  const GATE_CONFIG_PATTERNS = [
8
10
  /^tsconfig(\..+)?\.json$/,
9
11
  /^vitest\.config\.[mc]?[jt]s$/,
10
12
  /^vite\.config\.[mc]?[jt]s$/,
11
- /^jest\.config\.[mc]?[jt]s$/,
13
+ /^jest\.config\.([mc]?[jt]s|json)$/,
12
14
  /^eslint\.config\.[mc]?[jt]s$/,
13
15
  /^\.eslintrc(\.(json|js|cjs|ya?ml))?$/,
14
16
  /^\.prettierrc(\.(json|js|cjs|mjs|ya?ml|toml))?$/,
@@ -19,14 +21,15 @@ const GATE_CONFIG_PATTERNS = [
19
21
  /^slop-scan\.config\.json$/,
20
22
  /^\.lintstagedrc(\.(json|js|cjs|mjs|ya?ml))?$/,
21
23
  /^lint-staged\.config\.[mc]?js$/,
22
- /^pyproject\.toml$/,
23
24
  /^ruff\.toml$/,
24
25
  /^\.ruff\.toml$/,
25
26
  /^\.flake8$/,
26
- /^mypy\.ini$/,
27
+ /^\.?mypy\.ini$/,
28
+ /^\.?pylintrc$/,
29
+ /^pytest\.ini$/,
27
30
  /^\.golangci\.(ya?ml|toml|json)$/,
28
- /^clippy\.toml$/,
29
- /^rustfmt\.toml$/,
31
+ /^\.?clippy\.toml$/,
32
+ /^\.?rustfmt\.toml$/,
30
33
  ];
31
34
 
32
35
  // A path under `.bkit/templates/` (bkit's reference copies, refreshed on every upgrade)
@@ -119,6 +122,13 @@ function stateDir() {
119
122
  return path.join(os.tmpdir(), "bkit-gateguard");
120
123
  }
121
124
 
125
+ // Dedup scope: the session, narrowed to one agent when the host names it. A Claude Code
126
+ // subagent shares its parent's session_id and carries its own agent_id.
127
+ function dedupKey(sessionId, agentId) {
128
+ const sid = typeof sessionId === "string" ? sessionId : "no-session";
129
+ return typeof agentId === "string" && agentId ? `${sid}.${agentId}` : sid;
130
+ }
131
+
122
132
  function stateFile(sessionId) {
123
133
  const safe = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 128) || "no-session";
124
134
  return path.join(stateDir(), safe + ".json");
@@ -0,0 +1,23 @@
1
+ // --- Secret-file read tier: identical in the Cursor and Google Antigravity guardrails hooks
2
+ // (bkit renders it from one source). Same policy as Claude's settings.json `Read(...)` deny /
3
+ // ask rows and opencode's `permission.read` map; each host maps a tier to its own output
4
+ // shape and wording.
5
+
6
+ /**
7
+ * The read tier for a file path (`/` or `\` separated), first match wins:
8
+ * `{ tier: "deny", path }` — private-key material: `*.pem`, `*.p12`, `id_rsa`;
9
+ * `{ tier: "ask", path }` — an env / secrets file: `.env`, `.env.*` except `.env.example`;
10
+ * null — nothing to say.
11
+ */
12
+ function classifyRead(filePath) {
13
+ const p = String(filePath || "").replace(/\\/g, "/");
14
+ if (!p) return null;
15
+ if (/\.pem$/i.test(p) || /\.p12$/i.test(p) || /(^|\/)id_rsa$/i.test(p)) {
16
+ return { tier: "deny", path: p };
17
+ }
18
+ const base = p.split("/").pop() || p;
19
+ if (base === ".env" || (/^\.env\./.test(base) && base !== ".env.example")) {
20
+ return { tier: "ask", path: p };
21
+ }
22
+ return null;
23
+ }
@@ -0,0 +1,259 @@
1
+ // --- ReadGuard engine: identical in every host's hook (bkit renders it from one source).
2
+ // Needs `fs`, `os` and `path` in scope; the host's own code above declares them.
3
+
4
+ // Read tools stop here when the call gives no limit (Claude Code, opencode).
5
+ const READ_TOOL_DEFAULT_LIMIT = 2000;
6
+ // Larger files are not line-counted: a whole-file read of one stays open-ended and a
7
+ // `tail` of one is not tracked.
8
+ const LINE_COUNT_MAX_BYTES = 4 * 1024 * 1024;
9
+ // Stored end of an open-ended range (`cat`, `sed -n 'A,$p'`) on an uncounted file.
10
+ const OPEN_END = Number.MAX_SAFE_INTEGER;
11
+
12
+ // Outside quotes, any of these makes a command more than one plain read (pipe, list,
13
+ // redirect, substitution, glob, escape); such a command is not tracked.
14
+ const SHELL_COMPLEX_CHARS = new Set([..."|;&<>`$(){}*?[]\\\n"]);
15
+
16
+ /**
17
+ * Words of a single plain shell command, quotes removed; null when the command
18
+ * carries anything ReadGuard does not model (see SHELL_COMPLEX_CHARS, `$` or a
19
+ * backtick inside double quotes, unbalanced quotes).
20
+ */
21
+ function shellWords(cmd) {
22
+ const words = [];
23
+ let word = null;
24
+ let quote = null;
25
+ for (const ch of String(cmd).trim()) {
26
+ if (quote) {
27
+ if (ch === quote) quote = null;
28
+ else if (quote === '"' && (ch === "$" || ch === "`" || ch === "\\")) return null;
29
+ else word += ch;
30
+ continue;
31
+ }
32
+ if (ch === "'" || ch === '"') {
33
+ quote = ch;
34
+ word = word ?? "";
35
+ } else if (ch === " " || ch === "\t") {
36
+ if (word !== null) words.push(word);
37
+ word = null;
38
+ } else if (SHELL_COMPLEX_CHARS.has(ch)) {
39
+ return null;
40
+ } else {
41
+ word = (word ?? "") + ch;
42
+ }
43
+ }
44
+ if (quote) return null;
45
+ if (word !== null) words.push(word);
46
+ return words;
47
+ }
48
+
49
+ /** `head` / `tail` line count: `-n N`, `-nN`, `-N`, `--lines=N`; tail also `+N`. */
50
+ function lineCountArg(args) {
51
+ const rest = [];
52
+ let count = { n: 10, fromStart: false };
53
+ for (let i = 0; i < args.length; i++) {
54
+ const a = args[i];
55
+ let v = null;
56
+ if (a === "-n" || a === "--lines") v = args[++i];
57
+ else if (/^-n.+/.test(a)) v = a.slice(2);
58
+ else if (/^--lines=/.test(a)) v = a.slice("--lines=".length);
59
+ else if (/^-\d+$/.test(a)) v = a.slice(1);
60
+ else if (a.startsWith("-")) return null;
61
+ else {
62
+ rest.push(a);
63
+ continue;
64
+ }
65
+ const m = /^(\+)?(\d+)$/.exec(v ?? "");
66
+ if (!m) return null;
67
+ count = { n: Number(m[2]), fromStart: Boolean(m[1]) };
68
+ }
69
+ return { count, files: rest };
70
+ }
71
+
72
+ /**
73
+ * File reads a shell command performs, as `[{ file, start, end }]` or
74
+ * `[{ file, tail }]`: `cat FILE…`, `sed -n 'A,Bp' FILE…`, `head` / `tail` with a
75
+ * line count. Anything else (pipes, globs, other programs, other flags) → [].
76
+ */
77
+ function shellReadTargets(cmd, cwd) {
78
+ const words = shellWords(cmd);
79
+ if (!words || words.length < 2) return [];
80
+ const prog = words[0].replace(/^.*\//, "");
81
+ const args = words.slice(1);
82
+ const at = (f) => path.resolve(cwd, f);
83
+
84
+ if (prog === "cat") {
85
+ const files = args.filter((a) => !a.startsWith("-"));
86
+ return files.map((f) => ({ file: at(f), start: 1, end: OPEN_END }));
87
+ }
88
+ if (prog === "sed") {
89
+ if (args[0] !== "-n" || args.length < 3) return [];
90
+ const m = /^(\d+)(?:,(\d+|\$))?p$/.exec(args[1]);
91
+ if (!m || args.slice(2).some((a) => a.startsWith("-"))) return [];
92
+ const start = Number(m[1]);
93
+ const end = m[2] === undefined ? start : m[2] === "$" ? OPEN_END : Number(m[2]);
94
+ return args.slice(2).map((f) => ({ file: at(f), start, end }));
95
+ }
96
+ if (prog === "head" || prog === "tail") {
97
+ const parsed = lineCountArg(args);
98
+ if (!parsed) return [];
99
+ const { count, files } = parsed;
100
+ if (prog === "head") return files.map((f) => ({ file: at(f), start: 1, end: count.n }));
101
+ if (count.fromStart) return files.map((f) => ({ file: at(f), start: count.n, end: OPEN_END }));
102
+ return files.map((f) => ({ file: at(f), tail: count.n }));
103
+ }
104
+ return [];
105
+ }
106
+
107
+ /** A read tool's target: 1-based `start` plus `limit` lines, or an explicit `end`. */
108
+ function toolReadTarget(file, cwd, start, limit, end) {
109
+ if (typeof file !== "string" || !file) return [];
110
+ const s = Number.isInteger(start) && start > 0 ? start : 1;
111
+ const e =
112
+ Number.isInteger(end) && end >= s
113
+ ? end
114
+ : s + (Number.isInteger(limit) && limit > 0 ? limit : READ_TOOL_DEFAULT_LIMIT) - 1;
115
+ return [{ file: path.resolve(cwd, file), start: s, end: e }];
116
+ }
117
+
118
+ function countLines(file) {
119
+ const text = fs.readFileSync(file, "utf-8");
120
+ if (text.length === 0) return 0;
121
+ let n = 0;
122
+ for (let i = text.indexOf("\n"); i >= 0; i = text.indexOf("\n", i + 1)) n++;
123
+ return text.endsWith("\n") ? n : n + 1;
124
+ }
125
+
126
+ /** `[start, end]` clipped to the file's line count, or null when not trackable. */
127
+ function resolveRange(target, lines) {
128
+ if (target.tail !== undefined) {
129
+ if (lines === null) return null;
130
+ return [Math.max(1, lines - target.tail + 1), Math.max(1, lines)];
131
+ }
132
+ const end = lines === null ? target.end : Math.min(target.end, Math.max(1, lines));
133
+ return target.start > end ? null : [target.start, end];
134
+ }
135
+
136
+ function mergeRanges(ranges) {
137
+ const sorted = [...ranges].sort((a, b) => a[0] - b[0]);
138
+ const out = [];
139
+ for (const r of sorted) {
140
+ const last = out[out.length - 1];
141
+ if (last && r[0] <= last[1] + 1) last[1] = Math.max(last[1], r[1]);
142
+ else out.push([r[0], r[1]]);
143
+ }
144
+ return out;
145
+ }
146
+
147
+ function isCovered(ranges, [start, end]) {
148
+ return mergeRanges(ranges).some(([s, e]) => s <= start && end <= e);
149
+ }
150
+
151
+ function readStateDir() {
152
+ return path.join(os.tmpdir(), "bkit-readguard");
153
+ }
154
+
155
+ function safeKey(value, fallback) {
156
+ const s = typeof value === "string" ? value.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 128) : "";
157
+ return s || fallback;
158
+ }
159
+
160
+ // One log per (session, agent). A subagent that shares its parent's session id still
161
+ // gets its own log when the host passes an agent id.
162
+ function readLogFile(sessionId, agentId) {
163
+ return path.join(
164
+ readStateDir(),
165
+ `${safeKey(sessionId, "no-session")}.${safeKey(agentId, "main")}.json`,
166
+ );
167
+ }
168
+
169
+ // Absent log is the normal first-read case (guarded, no throw); a corrupt one throws
170
+ // to the host's top-level fail-open boundary and that one call no-ops.
171
+ function loadReadLog(file) {
172
+ if (!fs.existsSync(file)) return { files: {} };
173
+ const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
174
+ return parsed && typeof parsed.files === "object" && parsed.files ? parsed : { files: {} };
175
+ }
176
+
177
+ // Opportunistic TTL: drops logs older than 24h.
178
+ function gcOldReadLogs() {
179
+ const dir = readStateDir();
180
+ if (!fs.existsSync(dir)) return;
181
+ const cutoff = Date.now() - 24 * 60 * 60 * 1000;
182
+ for (const name of fs.readdirSync(dir)) {
183
+ const f = path.join(dir, name);
184
+ const stat = fs.statSync(f, { throwIfNoEntry: false });
185
+ if (stat && stat.mtimeMs < cutoff) fs.rmSync(f, { force: true });
186
+ }
187
+ }
188
+
189
+ /**
190
+ * Forgets every read of a session, all its agents included. Hosts call it when the
191
+ * conversation is summarised: earlier read output is no longer in context.
192
+ */
193
+ function resetReadLog(sessionId) {
194
+ const dir = readStateDir();
195
+ if (!fs.existsSync(dir)) return;
196
+ const prefix = `${safeKey(sessionId, "no-session")}.`;
197
+ for (const name of fs.readdirSync(dir)) {
198
+ if (name.startsWith(prefix)) fs.rmSync(path.join(dir, name), { force: true });
199
+ }
200
+ }
201
+
202
+ function displayPath(file, cwd) {
203
+ const rel = path.relative(cwd, file);
204
+ return rel && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel : file;
205
+ }
206
+
207
+ function repeatReadMessage(repeats, cwd) {
208
+ const lines = repeats.map(
209
+ ({ file, range }) =>
210
+ `- \`${displayPath(file, cwd)}\` lines ${range[0]}-${range[1] === OPEN_END ? "end" : range[1]}`,
211
+ );
212
+ return (
213
+ `[bkit ReadGuard] Repeat read this conversation - unchanged since your last read:\n` +
214
+ `${lines.join("\n")}\n` +
215
+ `Use the earlier output; do NOT read these lines again. Re-read ONLY if that output is no longer in your context (summarised, or read by another agent).\n` +
216
+ `Advisory — proceed once satisfied.`
217
+ );
218
+ }
219
+
220
+ /**
221
+ * The advisory for reading `targets` again, or null when ReadGuard is off, nothing is
222
+ * trackable, or no target repeats an earlier read of the same unchanged file by the
223
+ * same (session, agent). Records every trackable target.
224
+ */
225
+ function repeatReadAdvice(targets, sessionId, agentId, cwd) {
226
+ if (process.env.BKIT_READGUARD === "off") return null;
227
+ if (!Array.isArray(targets) || targets.length === 0) return null;
228
+
229
+ const logFile = readLogFile(sessionId, agentId);
230
+ const log = loadReadLog(logFile);
231
+ const repeats = [];
232
+ let changed = false;
233
+
234
+ for (const target of targets) {
235
+ const stat = fs.statSync(target.file, { throwIfNoEntry: false });
236
+ if (!stat || !stat.isFile()) continue;
237
+ const lines = stat.size <= LINE_COUNT_MAX_BYTES ? countLines(target.file) : null;
238
+ const range = resolveRange(target, lines);
239
+ if (!range) continue;
240
+
241
+ const prev = log.files[target.file];
242
+ const fresh = Boolean(prev) && prev.mtimeMs === stat.mtimeMs && prev.size === stat.size;
243
+ if (fresh && isCovered(prev.ranges, range)) repeats.push({ file: target.file, range });
244
+ log.files[target.file] = {
245
+ mtimeMs: stat.mtimeMs,
246
+ size: stat.size,
247
+ ranges: mergeRanges([...(fresh ? prev.ranges : []), range]),
248
+ };
249
+ changed = true;
250
+ }
251
+
252
+ if (changed) {
253
+ fs.mkdirSync(readStateDir(), { recursive: true });
254
+ fs.writeFileSync(logFile, JSON.stringify(log), "utf-8");
255
+ }
256
+ gcOldReadLogs();
257
+
258
+ return repeats.length > 0 ? repeatReadMessage(repeats, cwd) : null;
259
+ }
@@ -0,0 +1,67 @@
1
+ // Read / shell payload adapter, shared by the Claude Code, Cursor, Codex and Antigravity
2
+ // hooks: `{ tool_name, tool_input, session_id | conversation_id, agent_id?, cwd }`.
3
+ // Antigravity's own envelope is converted first (`antigravity-hook.js`).
4
+ const READ_TOOLS = new Set(["Read", "view_file"]);
5
+ const SHELL_TOOLS = new Set([
6
+ "Bash",
7
+ "bash",
8
+ "Shell",
9
+ "shell",
10
+ "local_shell",
11
+ "exec",
12
+ "exec_command",
13
+ "run_command",
14
+ "RunCommand",
15
+ ]);
16
+ const COMPACT_EVENTS = new Set(["PreCompact", "preCompact"]);
17
+ const SHELL_WRAPPERS = new Set(["bash", "sh", "zsh"]);
18
+
19
+ /** A shell command as one string; unwraps an argv `["bash", "-lc", "<cmd>"]`. */
20
+ function shellCommand(input) {
21
+ const cmd = input.command ?? input.cmd ?? input.CommandLine;
22
+ if (!Array.isArray(cmd)) return typeof cmd === "string" ? cmd : "";
23
+ const isWrapped =
24
+ cmd.length === 3 &&
25
+ SHELL_WRAPPERS.has(String(cmd[0]).replace(/^.*\//, "")) &&
26
+ /^-l?c$/.test(cmd[1]);
27
+ return isWrapped ? String(cmd[2]) : cmd.join(" ");
28
+ }
29
+
30
+ function intOrUndefined(value) {
31
+ const n = typeof value === "string" ? Number(value) : value;
32
+ return Number.isInteger(n) ? n : undefined;
33
+ }
34
+
35
+ // Pure: takes the already-parsed hook payload, returns the advisory text or null. A
36
+ // compaction event clears the session's read log and returns null. Never touches
37
+ // process.stdin / process.stdout — the driver below owns both.
38
+ function bkitReadguard(payload) {
39
+ const sessionId = payload.session_id ?? payload.conversation_id;
40
+ if (COMPACT_EVENTS.has(payload.hook_event_name)) {
41
+ resetReadLog(sessionId);
42
+ return null;
43
+ }
44
+ const tool = payload.tool_name;
45
+ const input = payload.tool_input ?? {};
46
+ const roots = payload.workspace_roots;
47
+ const cwd =
48
+ payload.cwd ??
49
+ input.working_directory ??
50
+ (Array.isArray(roots) && typeof roots[0] === "string" ? roots[0] : process.cwd());
51
+
52
+ let targets = [];
53
+ if (READ_TOOLS.has(tool)) {
54
+ const file =
55
+ input.file_path ?? input.path ?? input.filePath ?? input.target_file ?? input.AbsolutePath;
56
+ targets = toolReadTarget(
57
+ file,
58
+ cwd,
59
+ intOrUndefined(input.offset ?? input.StartLine),
60
+ intOrUndefined(input.limit),
61
+ intOrUndefined(input.EndLine),
62
+ );
63
+ } else if (SHELL_TOOLS.has(tool)) {
64
+ targets = shellReadTargets(shellCommand(input), cwd);
65
+ }
66
+ return repeatReadAdvice(targets, sessionId, payload.agent_id, cwd);
67
+ }
@@ -24,6 +24,7 @@ maxTurns: 150
24
24
  > **EXECUTION PROTOCOL:** Strict procedure, do not deviate.
25
25
  >
26
26
  > - **Rules:** Read `.agents/rules.md` → follow all `Universal Rules`; skip `Orchestrator Rules`.
27
+ > - **Code reads:** Locate first (symbol lookup or `grep -n`), then read only needed line ranges; never re-read unchanged files.
27
28
  > - **Order:** Execute Process steps sequentially unless stated otherwise.
28
29
  > - **No improv:** No ad-hoc steps, no skipping, no scope beyond this file.
29
30
  > - **Tools:** Verify every return; do not assume success.
@@ -22,6 +22,7 @@ maxTurns: 100
22
22
  > **EXECUTION PROTOCOL:** Strict procedure, do not deviate.
23
23
  >
24
24
  > - **Rules:** Read `.agents/rules.md` → follow all `Universal Rules`; skip `Orchestrator Rules`.
25
+ > - **Code reads:** Locate first (symbol lookup or `grep -n`), then read only needed line ranges; never re-read unchanged files.
25
26
  > - **Order:** Execute Process steps sequentially unless stated otherwise.
26
27
  > - **No improv:** No ad-hoc steps, no skipping, no scope beyond this file.
27
28
  > - **Tools:** Verify every return; do not assume success.