@cbartens/bkit 5.2.4 → 5.4.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 (271) hide show
  1. package/.bkit/README.md +27 -11
  2. package/.bkit/core/.agents/context.md +1 -1
  3. package/.bkit/core/.agents/docs.md +1 -1
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +1 -1
  5. package/.bkit/core/.agents/rules.md +18 -1
  6. package/.bkit/core/.bkit/README.md +26 -10
  7. package/.bkit/core/.bkit/cloud.md +40 -39
  8. package/.bkit/core/.bkit/comparison.md +68 -345
  9. package/.bkit/core/.bkit/install.md +16 -9
  10. package/.bkit/core/.bkit/lite.md +73 -0
  11. package/.bkit/core/.bkit/pipeline.md +346 -0
  12. package/.bkit/core/.bkit/prompts.md +90 -74
  13. package/.bkit/core/.bkit/providers.md +42 -23
  14. package/.bkit/core/.bkit/templates.md +138 -19
  15. package/.bkit/core/.bkit/trackers.md +49 -4
  16. package/.bkit/core/.bkit/workflows.md +144 -123
  17. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +1 -1
  18. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +7 -4
  19. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -5
  20. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  21. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  22. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  23. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  25. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  26. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  28. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  30. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  31. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  32. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  34. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  35. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  36. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +26 -21
  37. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  39. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  40. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  41. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  42. package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
  43. package/.bkit/core/docs/templates/bkit-audit-llm.md +22 -15
  44. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  45. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  47. package/.bkit/core/docs/templates/bkit-audit-prompts.md +7 -7
  48. package/.bkit/core/docs/templates/bkit-audit-red-team.md +12 -9
  49. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  50. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-security.md +14 -12
  52. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-testing.md +10 -8
  54. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  55. package/.bkit/core/docs/templates/bkit-plan.md +8 -6
  56. package/.bkit/core/engine/checks/after/auth.ts +9 -9
  57. package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
  58. package/.bkit/core/engine/checks/after/github.ts +29 -120
  59. package/.bkit/core/engine/checks/after/index.ts +2 -2
  60. package/.bkit/core/engine/checks/after/managed.ts +8 -28
  61. package/.bkit/core/engine/checks/after/tools.ts +3 -15
  62. package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
  63. package/.bkit/core/engine/checks/before/index.ts +7 -43
  64. package/.bkit/core/engine/checks/before/mcp.ts +17 -8
  65. package/.bkit/core/engine/checks/before/repo.ts +9 -12
  66. package/.bkit/core/engine/checks/status-holes.ts +4 -6
  67. package/.bkit/core/engine/checks/tips/catalogue.ts +76 -24
  68. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  69. package/.bkit/core/engine/checks/tips/index.ts +77 -26
  70. package/.bkit/core/engine/cli.ts +57 -27
  71. package/.bkit/core/engine/commands/analysis.ts +36 -26
  72. package/.bkit/core/engine/commands/comply.ts +42 -32
  73. package/.bkit/core/engine/commands/harvest.ts +12 -12
  74. package/.bkit/core/engine/commands/install/doctor.ts +57 -28
  75. package/.bkit/core/engine/commands/install/install.ts +73 -130
  76. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  77. package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
  78. package/.bkit/core/engine/commands/land.ts +156 -0
  79. package/.bkit/core/engine/commands/lib.ts +45 -18
  80. package/.bkit/core/engine/commands/registry.ts +2 -0
  81. package/.bkit/core/engine/commands/tips.ts +12 -5
  82. package/.bkit/core/engine/commands/workflow/branches.ts +386 -286
  83. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  84. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  85. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  86. package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  88. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  89. package/.bkit/core/engine/commands/workflow/prs.ts +15 -4
  90. package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
  91. package/.bkit/core/engine/commands/workflow/roadmap.ts +49 -53
  92. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  93. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  94. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  95. package/.bkit/core/engine/commands/workflow/steps.ts +25 -15
  96. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  97. package/.bkit/core/engine/commands/workflow/workflows.ts +436 -267
  98. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -2
  99. package/.bkit/core/engine/commands/workflow/worktrees.ts +24 -6
  100. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  101. package/.bkit/core/engine/install/manifest.ts +14 -7
  102. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  103. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  104. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  105. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  106. package/.bkit/core/engine/install/modules/core.ts +106 -70
  107. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  108. package/.bkit/core/engine/install/modules/index.ts +7 -1
  109. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  110. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  111. package/.bkit/core/engine/install/placeholders.ts +16 -35
  112. package/.bkit/core/engine/install/write.ts +59 -12
  113. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  114. package/.bkit/core/engine/render/hosts.ts +47 -67
  115. package/.bkit/core/engine/render/models.ts +29 -11
  116. package/.bkit/core/engine/shared/branches.ts +13 -0
  117. package/.bkit/core/engine/shared/egress.ts +3 -3
  118. package/.bkit/core/engine/shared/json.ts +18 -1
  119. package/.bkit/core/engine/shared/package-json.ts +63 -0
  120. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  121. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  122. package/.bkit/core/engine/shared/settings.ts +44 -0
  123. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  124. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  125. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  126. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  127. package/.bkit/core/prompts/bkit-audit-generate.md +103 -7
  128. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  129. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  130. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  131. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  132. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  133. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  134. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  135. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  136. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  137. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  138. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  139. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  140. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  141. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  142. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  143. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  144. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  145. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  146. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  147. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  148. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  149. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  150. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  151. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  152. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  153. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  154. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  155. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  156. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  157. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  158. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  159. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  160. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  161. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  162. package/.bkit/core/workflows/bkit-auto.md +2 -2
  163. package/.bkit/core/workflows/bkit-build.md +10 -10
  164. package/.bkit/core/workflows/bkit-debug.md +80 -44
  165. package/.bkit/core/workflows/bkit-design.md +22 -13
  166. package/.bkit/core/workflows/bkit-plan.md +33 -16
  167. package/.bkit/core/workflows/bkit-ship.md +87 -98
  168. package/.bkit/shared/.claude/bkit-cloud.md +58 -25
  169. package/.bkit/shared/.claude/settings.json +19 -0
  170. package/.bkit/shared/.cursor/mcp.json +2 -1
  171. package/.bkit/shared/.opencode/opencode.json +19 -1
  172. package/.bkit/shared/docs/deployments.md +49 -29
  173. package/.bkit/shared/docs/security.md +8 -6
  174. package/.bkit/shared/docs/testing.md +9 -5
  175. package/.bkit/shared/gitignore +1 -2
  176. package/.bkit/templates/.cursor/Dockerfile +30 -16
  177. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  178. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  179. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  180. package/.bkit/templates/.github/renovate.json5 +91 -12
  181. package/.bkit/templates/.github/workflows/bkit-ci.yml +73 -55
  182. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  183. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  184. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  185. package/.bkit/templates/.husky/pre-commit +6 -0
  186. package/.bkit/templates/.husky/pre-push +15 -3
  187. package/.bkit/templates/.lintstagedrc.json +5 -1
  188. package/.bkit/templates/.oxlintrc.json +21 -0
  189. package/.bkit/templates/docs/capabilities.md +1 -1
  190. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  191. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  192. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  193. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  194. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  195. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  196. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  197. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  198. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  199. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  200. package/CHANGELOG.md +98 -3
  201. package/README.md +252 -122
  202. package/dist/checks/after/auth.js +10 -11
  203. package/dist/checks/after/ci-yml.js +11 -14
  204. package/dist/checks/after/github.js +32 -125
  205. package/dist/checks/after/index.js +3 -2
  206. package/dist/checks/after/managed.js +8 -24
  207. package/dist/checks/after/tools.js +3 -16
  208. package/dist/checks/before/context-fetch.js +1 -21
  209. package/dist/checks/before/index.js +6 -42
  210. package/dist/checks/before/mcp.js +14 -9
  211. package/dist/checks/before/repo.js +8 -11
  212. package/dist/checks/status-holes.js +5 -7
  213. package/dist/checks/tips/catalogue.js +65 -18
  214. package/dist/checks/tips/detect.js +41 -2
  215. package/dist/checks/tips/index.js +61 -25
  216. package/dist/cli.js +52 -26
  217. package/dist/commands/analysis.js +21 -5
  218. package/dist/commands/comply.js +40 -31
  219. package/dist/commands/harvest.js +12 -13
  220. package/dist/commands/install/doctor.js +55 -23
  221. package/dist/commands/install/install.js +72 -122
  222. package/dist/commands/install/uninstall.js +165 -31
  223. package/dist/commands/install/upgrade.js +46 -39
  224. package/dist/commands/land.js +129 -0
  225. package/dist/commands/lib.js +41 -16
  226. package/dist/commands/registry.js +2 -0
  227. package/dist/commands/tips.js +10 -3
  228. package/dist/commands/workflow/branches.js +303 -248
  229. package/dist/commands/workflow/counters.js +17 -7
  230. package/dist/commands/workflow/disk.js +452 -0
  231. package/dist/commands/workflow/fids.js +39 -0
  232. package/dist/commands/workflow/issues.js +63 -27
  233. package/dist/commands/workflow/ledgers.js +3 -1
  234. package/dist/commands/workflow/locks.js +35 -130
  235. package/dist/commands/workflow/prs.js +8 -5
  236. package/dist/commands/workflow/repo.js +2 -2
  237. package/dist/commands/workflow/roadmap.js +50 -57
  238. package/dist/commands/workflow/runs.js +5 -5
  239. package/dist/commands/workflow/runtime.js +3 -2
  240. package/dist/commands/workflow/status.js +32 -12
  241. package/dist/commands/workflow/steps.js +19 -11
  242. package/dist/commands/workflow/tests.js +16 -3
  243. package/dist/commands/workflow/workflows.js +390 -249
  244. package/dist/commands/workflow/workstreams.js +4 -2
  245. package/dist/commands/workflow/worktrees.js +15 -6
  246. package/dist/install/cloud-env.js +10 -23
  247. package/dist/install/manifest.js +14 -7
  248. package/dist/install/modules/antigravity.js +15 -26
  249. package/dist/install/modules/claude.js +17 -21
  250. package/dist/install/modules/cloud.js +6 -2
  251. package/dist/install/modules/codex.js +15 -29
  252. package/dist/install/modules/core.js +95 -63
  253. package/dist/install/modules/cursor.js +6 -9
  254. package/dist/install/modules/index.js +6 -1
  255. package/dist/install/modules/opencode.js +41 -72
  256. package/dist/install/network-allowlist.js +62 -0
  257. package/dist/install/placeholders.js +16 -35
  258. package/dist/install/write.js +55 -15
  259. package/dist/ledgers/telemetry.js +5 -4
  260. package/dist/render/hosts.js +30 -55
  261. package/dist/render/models.js +20 -9
  262. package/dist/shared/branches.js +11 -0
  263. package/dist/shared/egress.js +0 -2
  264. package/dist/shared/json.js +14 -0
  265. package/dist/shared/package-json.js +61 -0
  266. package/dist/shared/package-roots.js +0 -8
  267. package/dist/shared/protected-paths.js +5 -122
  268. package/dist/shared/settings.js +23 -1
  269. package/dist/shared/timeouts.js +8 -7
  270. package/package.json +21 -17
  271. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -102,6 +102,20 @@ export function parseComplyPhase(value: unknown): ComplyPhase | null {
102
102
  : null;
103
103
  }
104
104
 
105
+ /**
106
+ * Where `bkit tips --workflow=<name>` runs: a phase workflow, `audit` (`@bkit-audit-generate`)
107
+ * or `utility` (the ledger and roadmap updaters).
108
+ */
109
+ export const TIPS_CONTEXTS = [...COMPLY_PHASES, "audit", "utility"] as const;
110
+ export type TipsContext = (typeof TIPS_CONTEXTS)[number];
111
+
112
+ /** Narrow an unknown string to `TipsContext` or return null if invalid. */
113
+ export function parseTipsContext(value: unknown): TipsContext | null {
114
+ return typeof value === "string" && (TIPS_CONTEXTS as readonly string[]).includes(value)
115
+ ? (value as TipsContext)
116
+ : null;
117
+ }
118
+
105
119
  export interface ParsedArgs {
106
120
  verb: Verb;
107
121
  /**
@@ -145,7 +159,7 @@ export interface ParsedArgs {
145
159
  /** `bkit tips --all`: print every firing tip, not just the top three. */
146
160
  tipsAll: boolean;
147
161
  /** `bkit tips --workflow=<name>`: the workflow whose tips go first; it prints one. */
148
- tipsWorkflow: ComplyPhase | null;
162
+ tipsWorkflow: TipsContext | null;
149
163
  }
150
164
 
151
165
  export interface UninstallFlags {
@@ -300,7 +314,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
300
314
  let complyPhase: ComplyPhase | null = null;
301
315
  let telemetrySubverb: TelemetrySubverb | null = null;
302
316
  let tipsAll = false;
303
- let tipsWorkflow: ComplyPhase | null = null;
317
+ let tipsWorkflow: TipsContext | null = null;
304
318
 
305
319
  // For `telemetry` verb: extract the sub-verb from the first remaining positional arg
306
320
  if (verb === "telemetry") {
@@ -457,10 +471,10 @@ export function parseArgs(argv: string[]): ParsedArgs {
457
471
  }
458
472
  if (flag.startsWith("workflow=") && verb === "tips") {
459
473
  const value = flag.slice("workflow=".length);
460
- tipsWorkflow = parseComplyPhase(value);
474
+ tipsWorkflow = parseTipsContext(value);
461
475
  if (tipsWorkflow === null) {
462
476
  console.error(
463
- `[bkit] Unknown workflow: "${value}". Valid values: ${COMPLY_PHASES.join(", ")}`,
477
+ `[bkit] Unknown workflow: "${value}". Valid values: ${TIPS_CONTEXTS.join(", ")}`,
464
478
  );
465
479
  process.exit(1);
466
480
  }
@@ -581,11 +595,15 @@ Usage:
581
595
  re-rendering. Copies under .bkit/templates/ are refreshed by
582
596
  install/upgrade and checked for staleness — adopt one by
583
597
  copying it elsewhere; that copy is yours. The CI gate.
598
+ Changes no managed file; rewrites .bkit/advisories.md.
584
599
  bkit upgrade [--to=<version>|--latest] [--auto-apply] [--dry-run]
585
600
  Upgrade everything installed (no module flags). Diffs old
586
601
  vs new templates; conflict list emitted to stderr. Use
587
602
  --auto-apply for CI (apply non-conflicting; exit non-zero
588
- on any conflict).
603
+ on any conflict). Only a whole file you edited since bkit
604
+ wrote it conflicts; rendered files (agents, commands,
605
+ skills, .bkit/*.md) are always re-rendered — bkit check
606
+ flags an edit to one.
589
607
  --to=<version> / --latest atomically BUMP @cbartens/bkit
590
608
  (pnpm add), then re-render + re-pin in one step — so a
591
609
  version bump can never drift from its rendered mirrors.
@@ -600,17 +618,22 @@ Usage:
600
618
  --nuke to force-remove manifest-listed files). Target with the
601
619
  same module flags as install (e.g. uninstall --claude); a
602
620
  targeted uninstall leaves core untouched.
603
- bkit doctor Read-only preflight + post-install advisory replay.
604
- Diagnose token surfaces and config drift. Exits 0.
621
+ bkit doctor Preflight + post-install advisory replay (changes no
622
+ managed file; rewrites .bkit/advisories.md). Diagnose
623
+ token surfaces and config drift. Exits 0.
605
624
  bkit tips [--workflow=<name>] [--all]
606
625
  Setup tips: what this repo has not set up yet, most useful
607
626
  first, each with a sentence to ask your agent. Top three
608
627
  by default; --workflow=design|plan|build|debug|ship puts
609
628
  the tips that matter there first and prints one (each
610
- workflow runs this at its close); --all lists every one.
611
- Local checks only. Exits 0.
629
+ workflow runs this at its close; audit and utility do the
630
+ same for audits and the ledger / roadmap updaters);
631
+ --all lists every one. Ends with a star line ("bkit-star"
632
+ in bkit.ignoreAdvisories silences it), except under
633
+ --workflow=audit|utility. Local checks only. Exits 0.
612
634
  bkit status Read-only host/provider status. Reports current host+provider
613
- (sampled from .opencode/opencode.json, .claude/, .cursor/).
635
+ (sampled from .claude/, .cursor/, package.json, and the
636
+ opencode agent model pins in .opencode/agents/).
614
637
  Writes nothing. Exits 0.
615
638
  bkit cursor Launch Cursor with .bkit/.env loaded into its environment.
616
639
  macOS GUI apps launched from the Dock/Finder do not inherit
@@ -630,12 +653,13 @@ Usage:
630
653
  bkit harvest Cross-repo harvest — COPIES consumer .bkit/stats.jsonl
631
654
  and MOVES .bkit/friction.jsonl into harvest/ (COUNT-ONLY
632
655
  for docs/deferrals.jsonl and docs/failures.jsonl).
633
- Reads consumer paths from docs/consumers.md.
656
+ Reads consumer paths from harvest/consumers.md.
634
657
  DESTRUCTIVE: harvested friction rows are REMOVED from
635
658
  the consumer, but only after they are fsync'd and read
636
659
  back from harvest/. stats.jsonl is never modified.
637
- harvest/ accumulates and is never cleared — commit it,
638
- as it is the only record of pruned rows. Never commits
660
+ harvest/ accumulates and is never cleared; it is
661
+ gitignored, so it is the only record of pruned rows —
662
+ back it up. Never commits
639
663
  in any repo. Deduplicates by per-kind composite
640
664
  identity. Advisory + fail-open: exits 0.
641
665
  bkit telemetry summary [--phase=<workflow>]
@@ -648,7 +672,7 @@ Usage:
648
672
  (design|plan|build|debug|ship). Without it, prints the
649
673
  ledger-health line only. Read-only: exits 0.
650
674
  bkit analysis Cross-repo analysis — reports counts/rates/elapsed-time,
651
- #183 size↔outcome regression, dispatch-size threshold,
675
+ change-size vs outcome regression, dispatch-size threshold,
652
676
  counterSource trust labelling, per-rule compliance
653
677
  rate over kind:"compliance" rows, and the
654
678
  unjustified-deferral rate per (subagent, model)
@@ -659,7 +683,7 @@ Usage:
659
683
 
660
684
  Core (implicit — no flag; installed/upgraded on every install):
661
685
  AGENTS.md (cross-host dispatch router), .agents/rules.md + .agents/context.md +
662
- .agents/docs.md + .agents/shortcuts.md + .agents/skills.md managed blocks, .gitignore +
686
+ .agents/docs.md + .agents/skills.md managed blocks, .gitignore +
663
687
  .gitattributes managed blocks, docs/, .bkit/*.md, .bkit/version, the template copies in
664
688
  .bkit/templates/, and the bkit:gate:* / bkit:deps:* package.json scripts every workflow
665
689
  runs (added when missing, never overwritten, left by uninstall). The tool scripts those
@@ -711,8 +735,10 @@ Dependency updaters (copy an example and own it):
711
735
  Cross-cutting / modifiers:
712
736
  --tracker=<name> Wire issue tracker integration. Values: github, linear, none
713
737
  (default). Records bkit.issueTracker in package.json and substitutes
714
- tracker snippets into command mirrors. Switching is free (re-run with
715
- a new value). Does NOT own AGENTS.md (which is tracker-agnostic).
738
+ tracker snippets into command mirrors. Re-renders every installed
739
+ host, and works alone (bkit install --tracker=github). Switching is
740
+ free; a switch removes the old linear MCP entry unless you edited it
741
+ (github always stays). Does NOT own AGENTS.md (tracker-agnostic).
716
742
 
717
743
  Install flags:
718
744
  --auto-revert On a Phase 3 blocker, automatically run uninstall and exit 1.
@@ -727,8 +753,9 @@ Uninstall flags:
727
753
  --opencode=<provider>
728
754
  Surgical provider removal: removes that provider's block from
729
755
  opencode.json + drops it from bkit.opencodeProviders. Does NOT remove
730
- agents/commands/gateguard. If the removed provider was active, re-render
731
- agents by running bkit install --opencode=<remaining> or bkit upgrade.
756
+ agents/commands/gateguard. If the removed provider was active, the first
757
+ remaining provider becomes active and the agents are re-rendered to its
758
+ model pins.
732
759
  Bare --opencode (no value) tears down the entire opencode host.
733
760
  --force Delete owned whole-file files even if consumer modified them.
734
761
  --nuke Delete ALL bkit-managed files regardless of tier/hash (requires confirm).
@@ -780,21 +807,23 @@ function commandsUsage(): string {
780
807
 
781
808
  /**
782
809
  * Validate the verb/module-flag combination before any dispatch
783
- * work runs. `install` requires >=1 module flag (bare install errors);
784
- * `check` / `upgrade` take NO module flags — they
785
- * operate on everything already installed, so a stray flag is a hard error
786
- * pointing at the no-flag form. Returns the error message to print, or `null`
810
+ * work runs. `install` requires >=1 module flag or `--tracker=` (which re-renders
811
+ * every installed host); a bare install errors. `check` / `upgrade` take NO module
812
+ * flags — they operate on everything already installed, so a stray flag is a hard
813
+ * error pointing at the no-flag form. Returns the error message to print, or `null`
787
814
  * when the combination is valid.
788
815
  */
789
816
  export function validateModuleFlagsForVerb(
790
817
  verb: Verb,
791
818
  moduleFlags: Set<ModuleFlag>,
819
+ tracker: IssueTracker | null = null,
792
820
  ): string | null {
793
- if (verb === "install" && moduleFlags.size === 0) {
821
+ if (verb === "install" && moduleFlags.size === 0 && tracker === null) {
794
822
  return (
795
823
  "[bkit] `bkit install` requires at least one module flag. Name what to install: " +
796
824
  "--claude, --cursor, --codex, --antigravity, --opencode=<provider> (plus opt-in " +
797
- `--auto=<${CLOUD_VARIANTS.join("|")}>). Run \`bkit help\` for usage.`
825
+ `--auto=<${CLOUD_VARIANTS.join("|")}>), or --tracker=<name> alone to switch the ` +
826
+ "tracker on what is installed. Run `bkit help` for usage."
798
827
  );
799
828
  }
800
829
  if ((verb === "check" || verb === "upgrade") && moduleFlags.size > 0) {
@@ -881,8 +910,9 @@ export async function main() {
881
910
  return;
882
911
  }
883
912
 
884
- // install requires >=1 module flag; check/upgrade take NONE (validateModuleFlagsForVerb).
885
- const moduleFlagsError = validateModuleFlagsForVerb(verb, moduleFlags);
913
+ // install requires >=1 module flag or --tracker=; check/upgrade take NONE
914
+ // (validateModuleFlagsForVerb).
915
+ const moduleFlagsError = validateModuleFlagsForVerb(verb, moduleFlags, tracker);
886
916
  if (moduleFlagsError) {
887
917
  console.error(moduleFlagsError);
888
918
  process.exit(1);
@@ -5,7 +5,8 @@
5
5
  // 2. Size↔outcome regression (logistic approximation: error ~ log(linesAdded)
6
6
  // + filesChanged) over `kind:"outcome"` rows.
7
7
  // 3. Dispatch-size threshold computation for plan-complexity-check / plan-split.
8
- // 4. `counterSource` trust labelling (model-self-report pre-P3, shell-bus post-P3).
8
+ // 4. `counterSource` trust labelling: each outcome row is joined to its `counter` row
9
+ // (model-self-report pre-P3, shell-bus post-P3).
9
10
  // 5. Per-rule compliance rate over `kind:"compliance"` rows.
10
11
  // 6. Per-`bkitVersion`→CHANGELOG release-attributed regression.
11
12
  //
@@ -18,32 +19,25 @@
18
19
 
19
20
  import * as fs from "node:fs";
20
21
  import * as path from "node:path";
21
- import { UNJUSTIFIED_REASON, foldFrom, type TelemetryEvent } from "../ledgers/telemetry.js";
22
+ import {
23
+ UNJUSTIFIED_REASON,
24
+ foldFrom,
25
+ type CounterPayload,
26
+ type OutcomePayload,
27
+ type TelemetryEnvelope,
28
+ type TelemetryEvent,
29
+ } from "../ledgers/telemetry.js";
22
30
  import { HARVEST_DEST_DIR } from "./harvest.js";
23
31
 
24
32
  // ---------------------------------------------------------------------------
25
33
  // Types
26
34
  // ---------------------------------------------------------------------------
27
35
 
28
- export interface OutcomeRow {
29
- ts: number;
30
- repo: string;
31
- bkitVersion: string;
32
- /** Ship-only: the merged PR number. Absent on non-ship workflow run rows. */
33
- prNumber?: number;
34
- linesAdded: number;
35
- linesDeleted: number;
36
- linesChanged: number;
37
- filesChanged: number;
38
- taskCount: number;
39
- durationSeconds: number;
40
- ciTrySuccess?: number;
41
- correctiveCommits?: number;
42
- reviewIterations?: number;
43
- deferrals: number;
44
- failures: number;
45
- counterSource?: string;
46
- }
36
+ /** A `kind:"outcome"` ledger row: the shared envelope plus the outcome payload. */
37
+ export type OutcomeRow = TelemetryEnvelope & OutcomePayload;
38
+
39
+ /** A `kind:"counter"` ledger row; `counterSource` lives here, never on the outcome row. */
40
+ export type CounterRow = TelemetryEnvelope & CounterPayload;
47
41
 
48
42
  export interface ComplianceRow {
49
43
  ts: number;
@@ -142,8 +136,9 @@ export interface RegressionResult {
142
136
  */
143
137
  dispatchSizeThreshold: number;
144
138
  /**
145
- * Trust tier split: rows labelled by counterSource.
146
- * "shell-bus" = post-P3 deterministic; "model-self-report" = pre-P3 untrusted.
139
+ * Trust tier split: an outcome row is shell-bus when a `counter` row with the same
140
+ * repo + workflow + parentSha carries `counterSource: "shell-bus"` (post-P3
141
+ * deterministic); every other outcome row is model-self-report (pre-P3 untrusted).
147
142
  */
148
143
  shellBusCount: number;
149
144
  modelSelfReportCount: number;
@@ -185,7 +180,18 @@ function isErrorRun(row: OutcomeRow, allRows: OutcomeRow[]): boolean {
185
180
  );
186
181
  }
187
182
 
188
- export function computeRegression(rows: OutcomeRow[]): RegressionResult {
183
+ /** Identity of one workflow run: the key the close writes on both its counter and outcome rows. */
184
+ function runKey(row: { repo: string; workflow: string; parentSha?: string }): string | undefined {
185
+ return row.parentSha ? JSON.stringify([row.repo, row.workflow, row.parentSha]) : undefined;
186
+ }
187
+
188
+ export function computeRegression(rows: OutcomeRow[], counterRows: CounterRow[]): RegressionResult {
189
+ const shellBusRuns = new Set<string>();
190
+ for (const c of counterRows) {
191
+ const key = runKey(c);
192
+ if (c.counterSource === "shell-bus" && key !== undefined) shellBusRuns.add(key);
193
+ }
194
+
189
195
  const buckets: SizeBucket[] = SIZE_BUCKETS.map((b) => ({
190
196
  label: b.label,
191
197
  minLines: b.min,
@@ -200,7 +206,8 @@ export function computeRegression(rows: OutcomeRow[]): RegressionResult {
200
206
 
201
207
  for (const row of rows) {
202
208
  // Trust tier labelling
203
- if (row.counterSource === "shell-bus") {
209
+ const key = runKey(row);
210
+ if (key !== undefined && shellBusRuns.has(key)) {
204
211
  shellBusCount++;
205
212
  } else {
206
213
  modelSelfReportCount++;
@@ -411,12 +418,15 @@ export function runAnalysis(paths: string[]): AnalysisReport {
411
418
  const events = [...state.values()];
412
419
 
413
420
  const outcomeRows: OutcomeRow[] = [];
421
+ const counterRows: CounterRow[] = [];
414
422
  const complianceRows: ComplianceRow[] = [];
415
423
  const deferralRows: DeferralRow[] = [];
416
424
 
417
425
  for (const ev of events) {
418
426
  if (ev.kind === "outcome") {
419
427
  outcomeRows.push(ev);
428
+ } else if (ev.kind === "counter") {
429
+ counterRows.push(ev);
420
430
  } else if (ev.kind === "compliance") {
421
431
  complianceRows.push(ev);
422
432
  } else if (ev.kind === "deferral") {
@@ -426,7 +436,7 @@ export function runAnalysis(paths: string[]): AnalysisReport {
426
436
 
427
437
  const counts = computeCounts(events);
428
438
  const elapsed = computeElapsedStats(outcomeRows);
429
- const regression = computeRegression(outcomeRows);
439
+ const regression = computeRegression(outcomeRows, counterRows);
430
440
  const complianceRates = computeComplianceRates(complianceRows);
431
441
  const versionCompliance = computeVersionCompliance(complianceRows);
432
442
  const deferralDiscipline = computeDeferralDiscipline(deferralRows);
@@ -17,9 +17,11 @@
17
17
  import { execFileSync } from "node:child_process";
18
18
  import * as fs from "node:fs";
19
19
  import * as path from "node:path";
20
+ import { readJsonFile } from "../shared/json.js";
20
21
  import { getPkgRoot } from "../shared/package-roots.js";
21
22
  import { isMirrorPath } from "../shared/protected-paths.js";
22
23
  import {
24
+ gitEnv,
23
25
  resolveGitSha,
24
26
  resolveRepoSlug,
25
27
  type TelemetryEnvelope,
@@ -52,26 +54,27 @@ export interface Violation {
52
54
  // ---------------------------------------------------------------------------
53
55
 
54
56
  export interface GitAdapter {
55
- /** Returns the diff stat paths (one per line, POSIX) for parentSha..HEAD. */
56
- diffPaths(parentSha: string, cwd: string): string[];
57
- /** Returns the subject line of HEAD. */
58
- headSubject(cwd: string): string;
57
+ /** Returns the diff stat paths (one per line, POSIX) for parentSha..head (HEAD by default). */
58
+ diffPaths(parentSha: string, cwd: string, head?: string): string[];
59
+ /** Returns the subject line of head (HEAD by default). */
60
+ headSubject(cwd: string, head?: string): string;
59
61
  }
60
62
 
61
63
  /** SHA charset guard — only raw hex SHAs from the ledger are accepted. */
62
64
  const SHA_RE = /^[0-9a-f]{7,40}$/;
63
65
 
64
66
  export const realGitAdapter: GitAdapter = {
65
- diffPaths(parentSha: string, cwd: string): string[] {
66
- if (!SHA_RE.test(parentSha)) {
67
+ diffPaths(parentSha: string, cwd: string, head = "HEAD"): string[] {
68
+ if (!SHA_RE.test(parentSha) || (head !== "HEAD" && !SHA_RE.test(head))) {
67
69
  console.error(
68
- `[bkit-comply] diffPaths: parentSha "${parentSha}" does not match /^[0-9a-f]{7,40}$/ — skipping diff`,
70
+ `[bkit-comply] diffPaths: "${parentSha}..${head}" is not a sha range — skipping diff`,
69
71
  );
70
72
  return [];
71
73
  }
72
74
  try {
73
- const output = execFileSync("git", ["diff", "--name-only", `${parentSha}..HEAD`], {
75
+ const output = execFileSync("git", ["diff", "--name-only", `${parentSha}..${head}`], {
74
76
  cwd,
77
+ env: gitEnv(),
75
78
  encoding: "utf8",
76
79
  stdio: ["ignore", "pipe", "ignore"],
77
80
  });
@@ -85,10 +88,12 @@ export const realGitAdapter: GitAdapter = {
85
88
  }
86
89
  },
87
90
 
88
- headSubject(cwd: string): string {
91
+ headSubject(cwd: string, head = "HEAD"): string {
92
+ if (head !== "HEAD" && !SHA_RE.test(head)) return "";
89
93
  try {
90
- return execFileSync("git", ["log", "-1", "--format=%s"], {
94
+ return execFileSync("git", ["log", "-1", "--format=%s", head], {
91
95
  cwd,
96
+ env: gitEnv(),
92
97
  encoding: "utf8",
93
98
  stdio: ["ignore", "pipe", "ignore"],
94
99
  }).trim();
@@ -153,6 +158,8 @@ export function ruleSkipCiNotHead(headSubject: string, phase: string): Violation
153
158
  export interface GraderInput {
154
159
  /** Git SHA of the parent commit (design-start / plan-start / etc.). */
155
160
  parentSha: string;
161
+ /** The commit graded, when not HEAD: ship's squash. */
162
+ headSha?: string;
156
163
  /** Workflow phase: design | plan | build | debug | ship */
157
164
  phase: string;
158
165
  /** Working directory for git commands. Defaults to process.cwd(). */
@@ -169,8 +176,8 @@ export function runGrader(input: GraderInput): Violation[] {
169
176
  try {
170
177
  const cwd = input.cwd ?? process.cwd();
171
178
  const adapter = input.gitAdapter ?? realGitAdapter;
172
- const diffPaths = adapter.diffPaths(input.parentSha, cwd);
173
- const headSubject = adapter.headSubject(cwd);
179
+ const diffPaths = adapter.diffPaths(input.parentSha, cwd, input.headSha);
180
+ const headSubject = adapter.headSubject(cwd, input.headSha);
174
181
 
175
182
  const violations: Violation[] = [];
176
183
 
@@ -275,21 +282,27 @@ export function appendComplianceRows(rows: ComplianceRow[], statsPath: string):
275
282
 
276
283
  /**
277
284
  * Grade `phase` over HEAD~1..HEAD (HEAD alone in a one-commit repo) and append
278
- * its compliance rows to `<cwd>/.bkit/stats.jsonl`. Fail-open: any error is
279
- * logged and returns null, so a close never stops on the grader.
285
+ * its compliance rows to `<cwd>/.bkit/stats.jsonl`. With `squashSha` (ship's
286
+ * close, run in the feature worktree) the squash commit is graded instead —
287
+ * its subject and `squash~1..squash` — so the grade covers the whole feature
288
+ * as it reaches main, not the worktree's last commit. Fail-open: any
289
+ * error is logged and returns null, so a close never stops on the grader.
280
290
  */
281
291
  export function gradeCompliance(
282
292
  cwd: string,
283
293
  phase: string,
284
294
  log: (m: string) => void,
295
+ squashSha?: string,
285
296
  ): Violation[] | null {
286
297
  try {
287
- const parentSha = resolveGitSha("HEAD~1", cwd) || resolveGitSha("HEAD", cwd);
298
+ const squashParent = squashSha === undefined ? "" : resolveGitSha(`${squashSha}~1`, cwd);
299
+ const parentSha = squashParent || resolveGitSha("HEAD~1", cwd) || resolveGitSha("HEAD", cwd);
288
300
  if (!parentSha) {
289
301
  log("[bkit-comply] cannot resolve a parent SHA (no commits?) — skipping grade");
290
302
  return null;
291
303
  }
292
- const violations = runGrader({ parentSha, phase, cwd });
304
+ const headSha = squashParent ? squashSha : undefined;
305
+ const violations = runGrader({ parentSha, phase, cwd, ...(headSha ? { headSha } : {}) });
293
306
  const rows = buildComplianceRows({
294
307
  violations,
295
308
  phase,
@@ -342,23 +355,20 @@ export function formatComplianceSummary(violations: Violation[]): string {
342
355
  * running bkit package's root). Returns "0.0.0" on any read/parse error (fail-open).
343
356
  */
344
357
  export function readBkitVersion(searchFrom?: string): string {
345
- try {
346
- // Walk up looking for a package.json with a `version` field; stop at the filesystem root.
347
- let dir = path.resolve(searchFrom ?? getPkgRoot());
348
- for (let i = 0; i < 8; i++) {
349
- const candidate = path.join(dir, "package.json");
350
- if (fs.existsSync(candidate)) {
351
- const pkg = JSON.parse(fs.readFileSync(candidate, "utf8")) as {
352
- version?: string;
353
- };
354
- if (typeof pkg.version === "string") return pkg.version;
355
- }
356
- const parent = path.dirname(dir);
357
- if (parent === dir) break;
358
- dir = parent;
358
+ // Walk up looking for a package.json with a `version` field; stop at the filesystem root.
359
+ let dir = path.resolve(searchFrom ?? getPkgRoot());
360
+ for (let i = 0; i < 8; i++) {
361
+ const candidate = path.join(dir, "package.json");
362
+ if (fs.existsSync(candidate)) {
363
+ const read = readJsonFile(candidate);
364
+ // Fail-open: a package.json that cannot be read ends the search with the default.
365
+ if (!read.ok || read.value === null) return "0.0.0";
366
+ const pkg = read.value as { version?: string };
367
+ if (typeof pkg.version === "string") return pkg.version;
359
368
  }
360
- } catch (_e) {
361
- void _e; // fail-open: version read errors return default
369
+ const parent = path.dirname(dir);
370
+ if (parent === dir) break;
371
+ dir = parent;
362
372
  }
363
373
  return "0.0.0";
364
374
  }
@@ -14,8 +14,8 @@
14
14
  // - The prune gate is byte-for-byte CONTENT, never identity.
15
15
  // - The central store ACCUMULATES across runs (never cleared) and holds every
16
16
  // DISTINCT row, deduped by content only. It is never rewritten from the fold. It is
17
- // the only record of pruned consumer friction until the caller commits it; readers
18
- // fold it.
17
+ // gitignored (private consumer content), so it is the only record of pruned consumer
18
+ // friction; readers fold it.
19
19
  // - Malformed consumer lines are NEVER pruned (not ours to delete).
20
20
  // - Grep-able [bkit-harvest] log lines.
21
21
  // - Relies on the tolerant `parse` for half-written tails.
@@ -24,7 +24,7 @@
24
24
  // copy -> fsync -> verify -> prune; a crash at any point re-copies idempotently on the
25
25
  // next run.
26
26
  //
27
- // Consumers are listed in `docs/consumers.md` (one absolute path per line).
27
+ // Consumers are listed in `harvest/consumers.md` (one absolute path per line).
28
28
  // See DE-34 for the shared-entrypoint + crash-isolation contract.
29
29
 
30
30
  import * as fs from "node:fs";
@@ -36,6 +36,7 @@ import {
36
36
  type FoldedState,
37
37
  type TelemetryEvent,
38
38
  } from "../ledgers/telemetry.js";
39
+ import { parseJson } from "../shared/json.js";
39
40
 
40
41
  // ---------------------------------------------------------------------------
41
42
  // Constants
@@ -52,7 +53,7 @@ export const HARVEST_PRUNE_FILES = ["friction.jsonl"] as const;
52
53
  /** Files to COUNT-ONLY from each consumer's `docs/` directory (metadata only). */
53
54
  export const HARVEST_COUNT_FILES = ["deferrals.jsonl", "failures.jsonl"] as const;
54
55
  /** Path (relative to bkit repo root) for the consumers list. */
55
- export const CONSUMERS_FILE = "docs/consumers.md";
56
+ export const CONSUMERS_FILE = "harvest/consumers.md";
56
57
  /**
57
58
  * Destination directory in bkit for harvested data. Repo root, NOT under `.bkit/`
58
59
  * (bkit's managed/installed surface).
@@ -91,11 +92,11 @@ export interface HarvestResult {
91
92
  }
92
93
 
93
94
  // ---------------------------------------------------------------------------
94
- // Read consumer list from `docs/consumers.md`
95
+ // Read consumer list from `harvest/consumers.md`
95
96
  // ---------------------------------------------------------------------------
96
97
 
97
98
  /**
98
- * Read the list of consumer repo root paths from `docs/consumers.md`.
99
+ * Read the list of consumer repo root paths from `harvest/consumers.md`.
99
100
  * Returns an array of absolute paths (non-empty lines, comments stripped).
100
101
  */
101
102
  export function readConsumerPaths(bkitRoot: string): string[] {
@@ -256,13 +257,12 @@ export function pruneConsumerFile(
256
257
 
257
258
  for (const line of raw.split("\n")) {
258
259
  if (line.trim() === "") continue;
259
- let event: TelemetryEvent;
260
- try {
261
- event = JSON.parse(line.trim()) as TelemetryEvent;
262
- } catch {
260
+ const parsed = parseJson(line.trim());
261
+ if (!parsed.ok) {
263
262
  kept.push(line); // malformed — never ours to delete
264
263
  continue;
265
264
  }
265
+ const event = parsed.value as TelemetryEvent;
266
266
  if (durable.rows.has(canonicalRow(stampRepo(event, consumerSlug)))) {
267
267
  removed++;
268
268
  continue;
@@ -304,7 +304,7 @@ function fsyncFile(filePath: string): void {
304
304
  // ---------------------------------------------------------------------------
305
305
 
306
306
  /**
307
- * Run harvest across all consumers listed in `docs/consumers.md`.
307
+ * Run harvest across all consumers listed in `harvest/consumers.md`.
308
308
  * Deduplicates the store by row content after collecting all rows.
309
309
  */
310
310
  export function runHarvest(bkitRoot: string): HarvestResult {
@@ -391,7 +391,7 @@ export function runHarvest(bkitRoot: string): HarvestResult {
391
391
  );
392
392
  if (totalPruned > 0) {
393
393
  console.error(
394
- `[bkit-harvest] ${totalPruned} row(s) now exist ONLY in ${HARVEST_DEST_DIR}/ — commit it to make them durable.`,
394
+ `[bkit-harvest] ${totalPruned} row(s) now exist ONLY in ${HARVEST_DEST_DIR}/ (gitignored) — back it up to make them durable.`,
395
395
  );
396
396
  }
397
397