@cbartens/bkit 5.2.4 → 5.3.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 (221) hide show
  1. package/.bkit/README.md +26 -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 +11 -0
  6. package/.bkit/core/.bkit/README.md +25 -10
  7. package/.bkit/core/.bkit/cloud.md +9 -8
  8. package/.bkit/core/.bkit/comparison.md +68 -345
  9. package/.bkit/core/.bkit/install.md +12 -6
  10. package/.bkit/core/.bkit/lite.md +73 -0
  11. package/.bkit/core/.bkit/pipeline.md +345 -0
  12. package/.bkit/core/.bkit/prompts.md +88 -73
  13. package/.bkit/core/.bkit/providers.md +41 -22
  14. package/.bkit/core/.bkit/templates.md +106 -17
  15. package/.bkit/core/.bkit/trackers.md +47 -1
  16. package/.bkit/core/.bkit/workflows.md +44 -43
  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-adoption.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -10
  22. package/.bkit/core/docs/templates/bkit-audit-llm.md +20 -14
  23. package/.bkit/core/docs/templates/bkit-audit-prompts.md +2 -2
  24. package/.bkit/core/docs/templates/bkit-audit-red-team.md +10 -8
  25. package/.bkit/core/docs/templates/bkit-audit-security.md +3 -3
  26. package/.bkit/core/docs/templates/bkit-audit-testing.md +4 -3
  27. package/.bkit/core/docs/templates/bkit-plan.md +8 -6
  28. package/.bkit/core/engine/checks/after/auth.ts +9 -9
  29. package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
  30. package/.bkit/core/engine/checks/after/github.ts +29 -120
  31. package/.bkit/core/engine/checks/after/index.ts +2 -2
  32. package/.bkit/core/engine/checks/after/managed.ts +8 -28
  33. package/.bkit/core/engine/checks/after/tools.ts +3 -15
  34. package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
  35. package/.bkit/core/engine/checks/before/index.ts +7 -43
  36. package/.bkit/core/engine/checks/before/mcp.ts +17 -8
  37. package/.bkit/core/engine/checks/before/repo.ts +9 -12
  38. package/.bkit/core/engine/checks/status-holes.ts +4 -5
  39. package/.bkit/core/engine/checks/tips/catalogue.ts +60 -24
  40. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  41. package/.bkit/core/engine/checks/tips/index.ts +37 -8
  42. package/.bkit/core/engine/cli.ts +39 -16
  43. package/.bkit/core/engine/commands/analysis.ts +36 -26
  44. package/.bkit/core/engine/commands/comply.ts +17 -16
  45. package/.bkit/core/engine/commands/harvest.ts +12 -12
  46. package/.bkit/core/engine/commands/install/doctor.ts +57 -28
  47. package/.bkit/core/engine/commands/install/install.ts +62 -126
  48. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  49. package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
  50. package/.bkit/core/engine/commands/lib.ts +35 -10
  51. package/.bkit/core/engine/commands/tips.ts +8 -5
  52. package/.bkit/core/engine/commands/workflow/branches.ts +4 -4
  53. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  54. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  55. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  56. package/.bkit/core/engine/commands/workflow/prs.ts +4 -2
  57. package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
  58. package/.bkit/core/engine/commands/workflow/roadmap.ts +4 -3
  59. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  60. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  61. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  62. package/.bkit/core/engine/commands/workflow/workflows.ts +15 -14
  63. package/.bkit/core/engine/commands/workflow/workstreams.ts +2 -1
  64. package/.bkit/core/engine/commands/workflow/worktrees.ts +13 -5
  65. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  66. package/.bkit/core/engine/install/manifest.ts +14 -7
  67. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  68. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  69. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  70. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  71. package/.bkit/core/engine/install/modules/core.ts +91 -70
  72. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  73. package/.bkit/core/engine/install/modules/index.ts +7 -1
  74. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  75. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  76. package/.bkit/core/engine/install/placeholders.ts +3 -18
  77. package/.bkit/core/engine/install/write.ts +59 -12
  78. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  79. package/.bkit/core/engine/render/hosts.ts +47 -67
  80. package/.bkit/core/engine/render/models.ts +29 -11
  81. package/.bkit/core/engine/shared/branches.ts +13 -0
  82. package/.bkit/core/engine/shared/egress.ts +3 -3
  83. package/.bkit/core/engine/shared/json.ts +18 -1
  84. package/.bkit/core/engine/shared/package-json.ts +63 -0
  85. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  86. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  87. package/.bkit/core/engine/shared/settings.ts +36 -0
  88. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  89. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  90. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  91. package/.bkit/core/prompts/bkit-audit-generate.md +60 -7
  92. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  93. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  94. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  95. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  96. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  97. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  98. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  99. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  100. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  101. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  102. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  103. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  104. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  105. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  106. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  107. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  108. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  109. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  110. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  111. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  112. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  113. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  114. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  115. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  116. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  117. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  118. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  119. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  120. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  121. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  122. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  123. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  124. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  125. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  126. package/.bkit/core/workflows/bkit-build.md +3 -3
  127. package/.bkit/core/workflows/bkit-debug.md +69 -33
  128. package/.bkit/core/workflows/bkit-design.md +2 -2
  129. package/.bkit/core/workflows/bkit-plan.md +11 -4
  130. package/.bkit/core/workflows/bkit-ship.md +5 -5
  131. package/.bkit/shared/.claude/bkit-cloud.md +46 -13
  132. package/.bkit/shared/.claude/settings.json +18 -0
  133. package/.bkit/shared/.cursor/mcp.json +2 -1
  134. package/.bkit/shared/.opencode/opencode.json +19 -1
  135. package/.bkit/shared/docs/deployments.md +20 -4
  136. package/.bkit/shared/docs/security.md +8 -6
  137. package/.bkit/shared/docs/testing.md +9 -5
  138. package/.bkit/templates/.cursor/Dockerfile +30 -16
  139. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  140. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  141. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  142. package/.bkit/templates/.github/renovate.json5 +91 -12
  143. package/.bkit/templates/.github/workflows/bkit-ci.yml +66 -53
  144. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  145. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  146. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  147. package/.bkit/templates/.husky/pre-push +8 -3
  148. package/.bkit/templates/.oxlintrc.json +21 -0
  149. package/.bkit/templates/docs/capabilities.md +1 -1
  150. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  151. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  152. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  153. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  154. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  155. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  156. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  157. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  158. package/CHANGELOG.md +50 -3
  159. package/README.md +258 -129
  160. package/dist/checks/after/auth.js +10 -11
  161. package/dist/checks/after/ci-yml.js +11 -14
  162. package/dist/checks/after/github.js +32 -125
  163. package/dist/checks/after/index.js +3 -2
  164. package/dist/checks/after/managed.js +8 -24
  165. package/dist/checks/after/tools.js +3 -16
  166. package/dist/checks/before/context-fetch.js +1 -21
  167. package/dist/checks/before/index.js +6 -42
  168. package/dist/checks/before/mcp.js +14 -9
  169. package/dist/checks/before/repo.js +8 -11
  170. package/dist/checks/status-holes.js +5 -6
  171. package/dist/checks/tips/catalogue.js +51 -18
  172. package/dist/checks/tips/detect.js +41 -2
  173. package/dist/checks/tips/index.js +25 -5
  174. package/dist/cli.js +34 -14
  175. package/dist/commands/analysis.js +21 -5
  176. package/dist/commands/comply.js +20 -18
  177. package/dist/commands/harvest.js +12 -13
  178. package/dist/commands/install/doctor.js +55 -23
  179. package/dist/commands/install/install.js +62 -118
  180. package/dist/commands/install/uninstall.js +165 -31
  181. package/dist/commands/install/upgrade.js +46 -39
  182. package/dist/commands/lib.js +32 -10
  183. package/dist/commands/tips.js +6 -3
  184. package/dist/commands/workflow/branches.js +3 -5
  185. package/dist/commands/workflow/counters.js +17 -7
  186. package/dist/commands/workflow/fids.js +39 -0
  187. package/dist/commands/workflow/ledgers.js +3 -1
  188. package/dist/commands/workflow/prs.js +3 -3
  189. package/dist/commands/workflow/repo.js +2 -2
  190. package/dist/commands/workflow/roadmap.js +4 -4
  191. package/dist/commands/workflow/runs.js +5 -5
  192. package/dist/commands/workflow/steps.js +1 -0
  193. package/dist/commands/workflow/tests.js +16 -3
  194. package/dist/commands/workflow/workflows.js +15 -15
  195. package/dist/commands/workflow/workstreams.js +2 -1
  196. package/dist/commands/workflow/worktrees.js +4 -5
  197. package/dist/install/cloud-env.js +10 -23
  198. package/dist/install/manifest.js +14 -7
  199. package/dist/install/modules/antigravity.js +15 -26
  200. package/dist/install/modules/claude.js +17 -21
  201. package/dist/install/modules/cloud.js +6 -2
  202. package/dist/install/modules/codex.js +15 -29
  203. package/dist/install/modules/core.js +82 -63
  204. package/dist/install/modules/cursor.js +6 -9
  205. package/dist/install/modules/index.js +6 -1
  206. package/dist/install/modules/opencode.js +41 -72
  207. package/dist/install/network-allowlist.js +62 -0
  208. package/dist/install/placeholders.js +3 -16
  209. package/dist/install/write.js +55 -15
  210. package/dist/ledgers/telemetry.js +5 -4
  211. package/dist/render/hosts.js +30 -55
  212. package/dist/render/models.js +20 -9
  213. package/dist/shared/branches.js +11 -0
  214. package/dist/shared/egress.js +0 -2
  215. package/dist/shared/json.js +14 -0
  216. package/dist/shared/package-json.js +61 -0
  217. package/dist/shared/package-roots.js +0 -8
  218. package/dist/shared/protected-paths.js +5 -122
  219. package/dist/shared/settings.js +18 -1
  220. package/package.json +21 -17
  221. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -1,12 +1,13 @@
1
1
  // checks/tips/catalogue.ts — the setup-tip catalogue: one entry per template, tool or
2
- // setting a consumer has not set up yet. Each workflow prints one tip at its close
3
- // (`bkit tips --workflow=<name>`); `bkit tips` prints the top three; `.bkit/advisories.md`
4
- // lists every firing tip under `Setup tips`.
2
+ // setting a consumer has not set up yet. Each workflow, `@bkit-audit-generate` and the
3
+ // ledger / roadmap updaters print one tip at their close (`bkit tips --workflow=<name>`,
4
+ // `audit` / `utility` for the agents); `bkit tips` prints the top three;
5
+ // `.bkit/advisories.md` lists every firing tip under `Setup tips`.
5
6
  //
6
7
  // Array order is the priority: comms first (can workflows reach anything), then change
7
8
  // quality (design → build), delivery (debug → ship), running cost, nice-to-have, and
8
9
  // setup-specific plumbing last. `workflows` names where a tip matters: a workflow shows
9
- // its own tips first, in array order, then the rest. Comms tips name every workflow, so
10
+ // its own tips first, in array order, then the rest. Comms tips name every context, so
10
11
  // they lead everywhere until fixed.
11
12
  //
12
13
  // Text rules: `line`, `why`, `caution` and `ask` are for the person, in plain English, and
@@ -29,29 +30,28 @@ import {
29
30
  isCloudOrCi,
30
31
  } from "../before/env.js";
31
32
  import { detectGhMcpToken, hasGithubMcpServer } from "../after/auth.js";
32
- import {
33
- buildTrackerSetupAdvisory,
34
- readConsumerCloudAgents,
35
- readConsumerIssueTracker,
36
- } from "../after/github.js";
33
+ import { buildTrackerSetupAdvisory } from "../after/github.js";
37
34
  import { buildDepUpdaterSetupAdvisory } from "../after/tools.js";
38
35
  import { detectInstalledHostModules } from "../../install/hosts.js";
39
36
  import { readBkitConfig } from "../../shared/settings.js";
40
- import type { ComplyPhase } from "../../cli.js";
37
+ import type { ComplyPhase, TipsContext } from "../../cli.js";
41
38
  import {
39
+ anyWorkflowMentions,
42
40
  claudeSettingsHas,
43
41
  codexTopLevelHas,
44
42
  exists,
43
+ hasJsTestRunner,
45
44
  hasLintStagedConfig,
46
45
  hasMcpServer,
46
+ hasTestLinter,
47
47
  unlockedMcpServers,
48
48
  } from "./detect.js";
49
49
 
50
50
  export interface SetupTip {
51
51
  /** `bkit.ignoreAdvisories` key; never an advisory id (those go in `advisories`). */
52
52
  id: string;
53
- /** Workflows the tip matters in; absent = shown only after every workflow's own tips. */
54
- workflows?: readonly ComplyPhase[];
53
+ /** Contexts the tip matters in; absent = shown only after every context's own tips. */
54
+ workflows?: readonly TipsContext[];
55
55
  /** Short label. */
56
56
  title: string;
57
57
  /** What `bkit tips` prints: what goes wrong today, then what to do. */
@@ -75,11 +75,14 @@ const hosts = (cwd: string) => detectInstalledHostModules(cwd);
75
75
  /** Every phase workflow. A value import of `COMPLY_PHASES` would cycle through cli.ts. */
76
76
  export const ALL_WORKFLOWS: readonly ComplyPhase[] = ["design", "plan", "build", "debug", "ship"];
77
77
 
78
+ /** Every `bkit tips --workflow=` context: the phase workflows, then the two agent closes. */
79
+ export const EVERY_CONTEXT: readonly TipsContext[] = [...ALL_WORKFLOWS, "audit", "utility"];
80
+
78
81
  export const SETUP_TIPS: readonly SetupTip[] = [
79
82
  // --- connect: can bkit talk to anything at all -------------------------------------
80
83
  {
81
84
  id: "tracker",
82
- workflows: ALL_WORKFLOWS,
85
+ workflows: EVERY_CONTEXT,
83
86
  title: "Connect an issue tracker",
84
87
  line: "bkit isn't connected to an issue tracker, so it can't read the task it's working on or record what it did. Connect GitHub or Linear, or switch this tip off if you don't want one.",
85
88
  why: "Every workflow starts by reading the issue it's working on and reports progress back to it as it goes. Without a tracker, you have to paste in what the agent should look at each time, and nothing records what changed or why.",
@@ -91,7 +94,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
91
94
  },
92
95
  {
93
96
  id: "gh-mcp",
94
- workflows: ALL_WORKFLOWS,
97
+ workflows: EVERY_CONTEXT,
95
98
  title: "Give bkit its GitHub token",
96
99
  line: "You chose GitHub as your tracker, but bkit has no GitHub token, so every attempt to read an issue or open a pull request will fail. Add the token.",
97
100
  why: "Choosing GitHub only tells bkit where your issues live. The token is what lets it actually sign in. Without it the setting looks right but nothing works, which is confusing to track down.",
@@ -100,12 +103,12 @@ export const SETUP_TIPS: readonly SetupTip[] = [
100
103
  "`.bkit/install.md` § Local env setup. The `github` server entry belongs in `.mcp.json` / `.cursor/mcp.json` (`.bkit/cloud.md` § MCP issue-tracker integration).",
101
104
  advisories: ["gh-mcp-token-unset-shell", "gh-mcp-token-empty-shell"],
102
105
  fires: (cwd) =>
103
- readConsumerIssueTracker(cwd) === "github" &&
106
+ readBkitConfig(cwd).issueTracker === "github" &&
104
107
  (!hasGithubMcpServer(cwd) || detectGhMcpToken(cwd) !== null),
105
108
  },
106
109
  {
107
110
  id: "bkit-env",
108
- workflows: ALL_WORKFLOWS,
111
+ workflows: EVERY_CONTEXT,
109
112
  title: "Create bkit's private settings file",
110
113
  line: "bkit's private settings file (.bkit/.env) is missing or has blank entries, so nothing that needs to sign in can. Create it and fill it in.",
111
114
  why: "This one file holds the sign-in tokens every bkit tool reads. It's never shared or committed. Most other tips depend on it, so do this one early.",
@@ -114,7 +117,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
114
117
  advisories: ["mcp-env-missing-dotenv", "mcp-env-blank-key-*"],
115
118
  fires: (cwd) => {
116
119
  if (isCloudOrCi()) return false;
117
- const tracker = readConsumerIssueTracker(cwd);
120
+ const tracker = readBkitConfig(cwd).issueTracker;
118
121
  return (
119
122
  detectMissingDotenv(cwd, tracker) !== null || detectBlankDotenvKeys(cwd, tracker).length > 0
120
123
  );
@@ -122,7 +125,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
122
125
  },
123
126
  {
124
127
  id: "direnv",
125
- workflows: ALL_WORKFLOWS,
128
+ workflows: EVERY_CONTEXT,
126
129
  title: "Load your tokens automatically",
127
130
  line: "Your sign-in tokens are saved in .bkit/.env but not being loaded, so sign-ins will fail even though the file looks right. Set up direnv so they load whenever you open the project.",
128
131
  why: "A saved file does nothing until something reads it. This is the most frustrating kind of breakage: nothing looks wrong, but every sign-in fails. direnv (a small tool that loads settings when you open a folder) fixes it once.",
@@ -131,7 +134,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
131
134
  advisories: ["mcp-env-direnv-missing", "mcp-env-direnv-not-allowed"],
132
135
  fires: (cwd) => {
133
136
  if (isCloudOrCi() || !exists(cwd, ".bkit/.env")) return false;
134
- const tracker = readConsumerIssueTracker(cwd);
137
+ const tracker = readBkitConfig(cwd).issueTracker;
135
138
  return (
136
139
  !exists(cwd, ".envrc") ||
137
140
  detectDirenvMissing(cwd, tracker) !== null ||
@@ -143,7 +146,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
143
146
  // --- quality: is the change good -----------------------------------------------------
144
147
  {
145
148
  id: "serena",
146
- workflows: ["design", "plan", "build"],
149
+ workflows: ["design", "plan", "build", "audit", "utility"],
147
150
  title: "Let agents look code up directly",
148
151
  line: "Agents are finding code by searching for words, which is slower, costs more, and misses things. Set up Serena so they can look code up directly.",
149
152
  why: 'Serena lets agents look up code the way your editor does ("where is this defined, and what uses it?") instead of guessing from text search and reading whole files. That means fewer accidental changes, fewer rounds of you correcting them, and lower running costs because they read less. It can only look things up, never change your files.',
@@ -153,7 +156,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
153
156
  },
154
157
  {
155
158
  id: "ci-workflow",
156
- workflows: ["build", "ship"],
159
+ workflows: ["build", "ship", "audit"],
157
160
  title: "Automatic checks on every change",
158
161
  line: "Nothing checks your changes automatically before they're merged, so broken code can land unnoticed. Add bkit's check workflow.",
159
162
  why: 'This runs your tests and checks on GitHub every time something changes, and bkit\'s ship step waits for it to pass before merging. Without it, "shipped" only means "merged", not "checked".',
@@ -191,6 +194,16 @@ export const SETUP_TIPS: readonly SetupTip[] = [
191
194
  steps: "`.bkit/templates.md` § slop-scan.",
192
195
  fires: (cwd) => !exists(cwd, "slop-scan.config.json"),
193
196
  },
197
+ {
198
+ id: "test-lint",
199
+ workflows: ["build"],
200
+ title: "Catch tests that can't fail",
201
+ line: "Nothing checks your test files, so a test that asserts nothing, or asserts only inside an if, still passes and the suite stays green having proved nothing. Add Oxlint with bkit's test rules.",
202
+ why: "Oxlint (a fast code linter) fails the check on a test with no assertion, a branch inside a test, an assertion that may never run, a malformed assertion, or a promise nobody waits for. Without it those tests pass whatever the code does.",
203
+ ask: "Run `pnpm add -D oxlint oxlint-tsgolint`, copy .bkit/templates/.oxlintrc.json to .oxlintrc.json, and set the `lint` script in package.json to run `oxlint -c .oxlintrc.json --type-aware --deny-warnings` (add `&&` and the current lint command if the script already has one). Then fix every hit in the tests themselves.",
204
+ steps: "`.bkit/templates.md` § Oxlint.",
205
+ fires: (cwd) => hasJsTestRunner(cwd) && !hasTestLinter(cwd),
206
+ },
194
207
  {
195
208
  id: "vale",
196
209
  workflows: ["design", "plan"],
@@ -222,7 +235,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
222
235
  ask: "Check my cloud-agent setup against .bkit/cloud.md: copy .bkit/templates/.github/workflows/bkit-cloud.yml to .github/workflows/bkit-cloud.yml and .bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh to .claude/hooks/ (for Cursor: .bkit/templates/.cursor/environment.json and .bkit/templates/.cursor/Dockerfile to .cursor/), run `gh secret set ANTHROPIC_API_KEY`, then tell me which dashboard settings are left.",
223
236
  steps: "`.bkit/cloud.md`; `.bkit/templates.md` § Cloud-agent workflow and § Cursor.",
224
237
  fires: (cwd) => {
225
- const cloud = readConsumerCloudAgents(cwd);
238
+ const cloud = readBkitConfig(cwd).cloudAgents;
226
239
  if (cloud === "none") return false;
227
240
  if (cloud === "cursor") {
228
241
  return !exists(cwd, ".cursor/environment.json") || !exists(cwd, ".cursor/Dockerfile");
@@ -298,9 +311,20 @@ export const SETUP_TIPS: readonly SetupTip[] = [
298
311
  },
299
312
 
300
313
  // --- optional: nice to have ------------------------------------------------------------
314
+ {
315
+ id: "issue-forms",
316
+ workflows: ["design", "plan", "debug"],
317
+ title: "Issue forms",
318
+ line: "Optional: add issue forms so every new issue asks for what the agent reads first.",
319
+ why: "Each workflow starts from the issue. A form for an idea, a well-defined change or a bug asks for the problem, what done looks like, or the steps to reproduce. Without one, issues often arrive as a title and a line, and the agent has to guess.",
320
+ ask: "Copy .bkit/templates/.github/ISSUE_TEMPLATE/ to .github/ISSUE_TEMPLATE/ and commit it to the default branch.",
321
+ steps: "`.bkit/templates.md` § Issue forms.",
322
+ fires: (cwd) =>
323
+ readBkitConfig(cwd).issueTracker === "github" && !exists(cwd, ".github/ISSUE_TEMPLATE"),
324
+ },
301
325
  {
302
326
  id: "graphify",
303
- workflows: ["design", "plan"],
327
+ workflows: ["design", "plan", "audit"],
304
328
  title: "A map of the code",
305
329
  line: "Optional: add graphify to keep an up-to-date map of how your code fits together.",
306
330
  why: "With a map, agents check what already exists before building it again. Without one, agents and reviews work out the structure from scratch each time. That's slower, and it's easy to miss how one change ripples into another part of the code.",
@@ -310,7 +334,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
310
334
  },
311
335
  {
312
336
  id: "dependabot-renovate",
313
- workflows: ["ship"],
337
+ workflows: ["ship", "audit"],
314
338
  title: "Automatic updates",
315
339
  line: "Nothing keeps the project's libraries up to date. Add an updater so you get small, safe updates instead of one big risky one later.",
316
340
  why: "An updater opens a small pull request whenever a library you use has a new version. Skip it and updates pile up into one large upgrade that's far more likely to break something.",
@@ -319,6 +343,18 @@ export const SETUP_TIPS: readonly SetupTip[] = [
319
343
  advisories: ["dep-updater-absent"],
320
344
  fires: (cwd) => buildDepUpdaterSetupAdvisory(cwd)?.id === "dep-updater-absent",
321
345
  },
346
+ {
347
+ id: "trivy",
348
+ workflows: ["ship", "audit"],
349
+ title: "Security scan",
350
+ line: "Nothing stops a change that adds a known-vulnerable library, a risky container setting or a leaked password from merging. Add the scan that fails the check when it finds one.",
351
+ why: "An updater only offers fixes, and only once a fixed version exists. The scan checks every change, plus once a day, so a known problem fails the check before it merges and one with no fix yet still shows up.",
352
+ ask: "Copy .bkit/templates/.github/workflows/bkit-trivy.yml to .github/workflows/bkit-trivy.yml, replace {{DEFAULT_BRANCH}} with my default branch, and commit it.",
353
+ steps:
354
+ "`.bkit/templates.md` § Trivy. Accept a finding in `.trivyignore.yaml` with `statement` + `expired_at`; never drop `--include-dev-deps`.",
355
+ fires: (cwd) =>
356
+ exists(cwd, ".github/workflows") && !anyWorkflowMentions(cwd, "aquasecurity/trivy"),
357
+ },
322
358
  {
323
359
  id: "prettier-tables",
324
360
  workflows: ["design", "plan"],
@@ -1,10 +1,10 @@
1
1
  // checks/tips/detect.ts — local-only probes the setup-tip catalogue keys on: host MCP
2
- // configs, host settings files, lint-staged config forms. No network.
2
+ // configs, host settings files, lint-staged and test-linter config forms. No network.
3
3
 
4
4
  import * as fs from "node:fs";
5
5
  import * as path from "node:path";
6
6
  import { parseJson } from "../../shared/json.js";
7
- import { readPackageJson } from "../../shared/package-json.js";
7
+ import { readDependencyNames, readPackageJson } from "../../shared/package-json.js";
8
8
 
9
9
  /** True when `rel` exists under `cwd`. */
10
10
  export const exists = (cwd: string, rel: string): boolean => fs.existsSync(path.join(cwd, rel));
@@ -136,9 +136,52 @@ const LINT_STAGED_CONFIGS = [
136
136
  "lint-staged.config.js",
137
137
  ];
138
138
 
139
+ /** True when any `.github/workflows/*.yml` / `*.yaml` contains `needle`. */
140
+ export function anyWorkflowMentions(cwd: string, needle: string): boolean {
141
+ const dir = path.join(cwd, ".github", "workflows");
142
+ if (!fs.existsSync(dir)) return false;
143
+ return fs
144
+ .readdirSync(dir)
145
+ .filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"))
146
+ .some((f) => readText(cwd, path.join(".github", "workflows", f)).includes(needle));
147
+ }
148
+
139
149
  /** True when lint-staged is configured: any of its config files, or `package.json` `lint-staged`. */
140
150
  export function hasLintStagedConfig(cwd: string): boolean {
141
151
  if (LINT_STAGED_CONFIGS.some((rel) => exists(cwd, rel))) return true;
142
152
  const pkg = readPackageJson(cwd);
143
153
  return pkg.ok && pkg.pkg["lint-staged"] !== undefined;
144
154
  }
155
+
156
+ const OXLINT_CONFIGS = [
157
+ ".oxlintrc.json",
158
+ ...["ts", "mts", "cts", "js", "mjs", "cjs"].map((ext) => `oxlint.config.${ext}`),
159
+ ];
160
+
161
+ const ESLINT_CONFIGS = [
162
+ ".eslintrc",
163
+ ...["json", "js", "cjs", "yaml", "yml"].map((ext) => `.eslintrc.${ext}`),
164
+ ...["js", "mjs", "cjs", "ts", "mts", "cts"].map((ext) => `eslint.config.${ext}`),
165
+ ];
166
+
167
+ /** A test-framework or test-library name inside an ESLint config means it lints tests. */
168
+ const TEST_LINT_PLUGIN = /vitest|jest|playwright|testing-library/i;
169
+
170
+ /** True when `package.json` lists a JS / TS test runner (Vitest or Jest) as a dependency. */
171
+ export const hasJsTestRunner = (cwd: string): boolean =>
172
+ readDependencyNames(cwd).some((name) => name === "vitest" || name === "jest");
173
+
174
+ /**
175
+ * True when the repo already lints its test files: an Oxlint config or `oxlint` dependency,
176
+ * or an ESLint config (file or `package.json` `eslintConfig`) that names a test plugin.
177
+ */
178
+ export function hasTestLinter(cwd: string): boolean {
179
+ if (OXLINT_CONFIGS.some((rel) => exists(cwd, rel))) return true;
180
+ if (readDependencyNames(cwd).includes("oxlint")) return true;
181
+ const eslintConfigs = ESLINT_CONFIGS.map((rel) => readText(cwd, rel));
182
+ const pkg = readPackageJson(cwd);
183
+ if (pkg.ok && pkg.pkg["eslintConfig"] !== undefined) {
184
+ eslintConfigs.push(JSON.stringify(pkg.pkg["eslintConfig"]));
185
+ }
186
+ return eslintConfigs.some((text) => TEST_LINT_PLUGIN.test(text));
187
+ }
@@ -7,8 +7,8 @@ import {
7
7
  type SuppressionNote,
8
8
  type SuppressionReporter,
9
9
  } from "../after/suppression.js";
10
- import type { ComplyPhase } from "../../cli.js";
11
- import { SETUP_TIPS, type SetupTip } from "./catalogue.js";
10
+ import type { TipsContext } from "../../cli.js";
11
+ import { ALL_WORKFLOWS, SETUP_TIPS, type SetupTip } from "./catalogue.js";
12
12
 
13
13
  /** Tips `bkit tips` prints without `--all` or `--workflow`. */
14
14
  export const TIPS_CAP = 3;
@@ -27,6 +27,17 @@ export const tipsIntro = (n: number) =>
27
27
  export const TIPS_DETAILS_POINTER =
28
28
  "Details for every tip: .bkit/advisories.md § Setup tips (refreshed by `bkit check`).";
29
29
 
30
+ /** `bkit.ignoreAdvisories` key that silences `STAR_TIP`. */
31
+ export const STAR_TIP_ID = "star";
32
+
33
+ /**
34
+ * Last line of `bkit tips` output while not silenced, in bare `bkit tips` and the phase
35
+ * workflows only — audits and the ledger / roadmap updaters often run back to back. Not a
36
+ * gap, so never in the checklist.
37
+ */
38
+ export const STAR_TIP =
39
+ "Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!";
40
+
30
41
  /** Intro of the Setup tips section: who reads which field, and how to silence a tip. */
31
42
  export const TIPS_SECTION_INTRO =
32
43
  "Things not set up yet, most useful first. For the person: each tip says what goes wrong today and a sentence to ask your agent. For an AI agent: follow each tip's Agent steps unless the person declines it. Silence a tip by adding its id to `bkit.ignoreAdvisories` in package.json. Full template catalogue: .bkit/templates.md.";
@@ -48,6 +59,8 @@ export interface TipsResult {
48
59
  tips: SetupTip[];
49
60
  /** Firing tips the root `bkit.ignoreAdvisories` silenced. */
50
61
  suppressed: SuppressionNote[];
62
+ /** False when the root `bkit.ignoreAdvisories` names `STAR_TIP_ID`. */
63
+ star: boolean;
51
64
  }
52
65
 
53
66
  /** Every firing tip in priority order, minus the ones the root package.json silences. */
@@ -60,7 +73,7 @@ export function collectTips(cwd: string, catalogue: readonly SetupTip[] = SETUP_
60
73
  if (isTipSilenced(tip, ignored)) suppressed.push({ id: tip.id, scope: "." });
61
74
  else tips.push(tip);
62
75
  }
63
- return { tips, suppressed };
76
+ return { tips, suppressed, star: !ignored.has(STAR_TIP_ID) };
64
77
  }
65
78
 
66
79
  /**
@@ -93,7 +106,7 @@ function tipTextLines(tip: SetupTip, n: number): string[] {
93
106
  return lines;
94
107
  }
95
108
 
96
- /** One tip as markdown paragraphs for a workflow's `## Setup Tips` section. */
109
+ /** One tip as markdown paragraphs for a workflow's `## bkit Tips` section. */
97
110
  function tipMarkdownLines(tip: SetupTip): string[] {
98
111
  const lines = [`**${tip.title}.** ${tip.line}`, "", `Ask your agent: "${tip.ask}"`];
99
112
  if (tip.caution) lines.push("", `Caution: ${tip.caution}`);
@@ -104,22 +117,38 @@ function tipMarkdownLines(tip: SetupTip): string[] {
104
117
  * `tips` with the ones that matter in `workflow` first, each group in catalogue order.
105
118
  * Comms tips name every workflow, so they stay first everywhere.
106
119
  */
107
- export function orderForWorkflow(tips: readonly SetupTip[], workflow: ComplyPhase): SetupTip[] {
120
+ export function orderForWorkflow(tips: readonly SetupTip[], workflow: TipsContext): SetupTip[] {
108
121
  const own = tips.filter((t) => t.workflows?.includes(workflow));
109
122
  return [...own, ...tips.filter((t) => !own.includes(t))];
110
123
  }
111
124
 
125
+ /** True when `STAR_TIP` closes the output in `workflow`: bare `bkit tips` or a phase workflow. */
126
+ export function starShownIn(workflow: TipsContext | null | undefined): boolean {
127
+ return !workflow || (ALL_WORKFLOWS as readonly string[]).includes(workflow);
128
+ }
129
+
112
130
  /**
113
- * `bkit tips` output, then where the rest live. `""` when no tip fires.
131
+ * `bkit tips` output, then where the rest live, then `STAR_TIP` when `star` is set and
132
+ * `starShownIn(workflow)`. `""` when no tip fires and no star line shows.
114
133
  * - `workflow`: the `WORKFLOW_TIPS_CAP` tips that matter most in that workflow, as
115
134
  * markdown paragraphs with no intro or numbers — the workflow appends them under its
116
- * own `## Setup Tips` heading.
135
+ * own `## bkit Tips` heading.
117
136
  * - neither: the top `TIPS_CAP` tips as a numbered terminal list.
118
137
  * - `all`: every tip as a numbered list (in the workflow's order when `workflow` is set).
119
138
  */
120
139
  export function formatTips(
121
140
  tips: readonly SetupTip[],
122
- opts: { all?: boolean; workflow?: ComplyPhase | null } = {},
141
+ opts: { all?: boolean; workflow?: TipsContext | null; star?: boolean } = {},
142
+ ): string {
143
+ const body = formatSetupTips(tips, opts);
144
+ if (!opts.star || !starShownIn(opts.workflow)) return body;
145
+ return body ? `${body}\n\n${STAR_TIP}` : STAR_TIP;
146
+ }
147
+
148
+ /** `formatTips` without `STAR_TIP`. */
149
+ function formatSetupTips(
150
+ tips: readonly SetupTip[],
151
+ opts: { all?: boolean; workflow?: TipsContext | null },
123
152
  ): string {
124
153
  if (tips.length === 0) return "";
125
154
  const ordered = opts.workflow ? orderForWorkflow(tips, opts.workflow) : [...tips];
@@ -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,6 +595,7 @@ 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
@@ -600,17 +615,22 @@ Usage:
600
615
  --nuke to force-remove manifest-listed files). Target with the
601
616
  same module flags as install (e.g. uninstall --claude); a
602
617
  targeted uninstall leaves core untouched.
603
- bkit doctor Read-only preflight + post-install advisory replay.
604
- Diagnose token surfaces and config drift. Exits 0.
618
+ bkit doctor Preflight + post-install advisory replay (changes no
619
+ managed file; rewrites .bkit/advisories.md). Diagnose
620
+ token surfaces and config drift. Exits 0.
605
621
  bkit tips [--workflow=<name>] [--all]
606
622
  Setup tips: what this repo has not set up yet, most useful
607
623
  first, each with a sentence to ask your agent. Top three
608
624
  by default; --workflow=design|plan|build|debug|ship puts
609
625
  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.
626
+ workflow runs this at its close; audit and utility do the
627
+ same for audits and the ledger / roadmap updaters);
628
+ --all lists every one. Ends with a star line ("star" in
629
+ bkit.ignoreAdvisories silences it), except under
630
+ --workflow=audit|utility. Local checks only. Exits 0.
612
631
  bkit status Read-only host/provider status. Reports current host+provider
613
- (sampled from .opencode/opencode.json, .claude/, .cursor/).
632
+ (sampled from .claude/, .cursor/, package.json, and the
633
+ opencode agent model pins in .opencode/agents/).
614
634
  Writes nothing. Exits 0.
615
635
  bkit cursor Launch Cursor with .bkit/.env loaded into its environment.
616
636
  macOS GUI apps launched from the Dock/Finder do not inherit
@@ -630,12 +650,13 @@ Usage:
630
650
  bkit harvest Cross-repo harvest — COPIES consumer .bkit/stats.jsonl
631
651
  and MOVES .bkit/friction.jsonl into harvest/ (COUNT-ONLY
632
652
  for docs/deferrals.jsonl and docs/failures.jsonl).
633
- Reads consumer paths from docs/consumers.md.
653
+ Reads consumer paths from harvest/consumers.md.
634
654
  DESTRUCTIVE: harvested friction rows are REMOVED from
635
655
  the consumer, but only after they are fsync'd and read
636
656
  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
657
+ harvest/ accumulates and is never cleared; it is
658
+ gitignored, so it is the only record of pruned rows —
659
+ back it up. Never commits
639
660
  in any repo. Deduplicates by per-kind composite
640
661
  identity. Advisory + fail-open: exits 0.
641
662
  bkit telemetry summary [--phase=<workflow>]
@@ -659,7 +680,7 @@ Usage:
659
680
 
660
681
  Core (implicit — no flag; installed/upgraded on every install):
661
682
  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 +
683
+ .agents/docs.md + .agents/skills.md managed blocks, .gitignore +
663
684
  .gitattributes managed blocks, docs/, .bkit/*.md, .bkit/version, the template copies in
664
685
  .bkit/templates/, and the bkit:gate:* / bkit:deps:* package.json scripts every workflow
665
686
  runs (added when missing, never overwritten, left by uninstall). The tool scripts those
@@ -712,7 +733,8 @@ Cross-cutting / modifiers:
712
733
  --tracker=<name> Wire issue tracker integration. Values: github, linear, none
713
734
  (default). Records bkit.issueTracker in package.json and substitutes
714
735
  tracker snippets into command mirrors. Switching is free (re-run with
715
- a new value). Does NOT own AGENTS.md (which is tracker-agnostic).
736
+ a new value); a switch removes the old tracker's MCP entry unless you
737
+ edited it. Does NOT own AGENTS.md (which is tracker-agnostic).
716
738
 
717
739
  Install flags:
718
740
  --auto-revert On a Phase 3 blocker, automatically run uninstall and exit 1.
@@ -727,8 +749,9 @@ Uninstall flags:
727
749
  --opencode=<provider>
728
750
  Surgical provider removal: removes that provider's block from
729
751
  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.
752
+ agents/commands/gateguard. If the removed provider was active, the first
753
+ remaining provider becomes active and the agents are re-rendered to its
754
+ model pins.
732
755
  Bare --opencode (no value) tears down the entire opencode host.
733
756
  --force Delete owned whole-file files even if consumer modified them.
734
757
  --nuke Delete ALL bkit-managed files regardless of tier/hash (requires confirm).
@@ -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);