@cbartens/bkit 5.4.0 → 5.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/.bkit/README.md +19 -7
  2. package/.bkit/core/.agents/rules.md +24 -9
  3. package/.bkit/core/.bkit/README.md +18 -6
  4. package/.bkit/core/.bkit/cloud.md +46 -15
  5. package/.bkit/core/.bkit/comparison.md +2 -2
  6. package/.bkit/core/.bkit/install.md +19 -18
  7. package/.bkit/core/.bkit/pipeline.md +3 -1
  8. package/.bkit/core/.bkit/prompts.md +38 -20
  9. package/.bkit/core/.bkit/providers.md +6 -6
  10. package/.bkit/core/.bkit/templates.md +44 -13
  11. package/.bkit/core/.bkit/trackers.md +99 -35
  12. package/.bkit/core/.bkit/workflows.md +50 -45
  13. package/.bkit/core/AGENTS.md +2 -2
  14. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  15. package/.bkit/core/docs/templates/bkit-audit-issues.md +22 -6
  16. package/.bkit/core/engine/checks/after/auth.ts +88 -45
  17. package/.bkit/core/engine/checks/after/ci-yml.ts +0 -1
  18. package/.bkit/core/engine/checks/after/github.ts +42 -78
  19. package/.bkit/core/engine/checks/after/index.ts +1 -6
  20. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  21. package/.bkit/core/engine/checks/before/env.ts +28 -18
  22. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  23. package/.bkit/core/engine/checks/tips/catalogue.ts +15 -2
  24. package/.bkit/core/engine/checks/tips/index.ts +5 -2
  25. package/.bkit/core/engine/cli.ts +7 -5
  26. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  27. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  28. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  29. package/.bkit/core/engine/commands/workflow/issues.ts +61 -63
  30. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  31. package/.bkit/core/engine/commands/workflow/prs.ts +3 -1
  32. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  33. package/.bkit/core/engine/commands/workflow/roadmap.ts +5 -1
  34. package/.bkit/core/engine/commands/workflow/steps.ts +2 -2
  35. package/.bkit/core/engine/commands/workflow/workflows.ts +9 -4
  36. package/.bkit/core/engine/commands/workflow/worktrees.ts +91 -14
  37. package/.bkit/core/engine/install/manifest.ts +31 -10
  38. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  39. package/.bkit/core/engine/install/modules/core.ts +153 -4
  40. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  41. package/.bkit/core/engine/install/write.ts +37 -1
  42. package/.bkit/core/engine/render/trackers.ts +35 -23
  43. package/.bkit/core/engine/shared/egress.ts +6 -0
  44. package/.bkit/core/engine/shared/settings.ts +130 -11
  45. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  46. package/.bkit/core/prompts/bkit-audit-generate.md +42 -12
  47. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  48. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  49. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  50. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  51. package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -0
  52. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  53. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  54. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  55. package/.bkit/core/prompts/bkit-design-generate.md +4 -1
  56. package/.bkit/core/prompts/bkit-plan-generate.md +5 -3
  57. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  58. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  59. package/.bkit/core/prompts/bkit-utility-update-decisions.md +3 -1
  60. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +3 -1
  61. package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
  62. package/.bkit/core/prompts/bkit-utility-update-failures.md +3 -1
  63. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +3 -1
  64. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +9 -2
  65. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  66. package/.bkit/core/workflows/bkit-auto.md +19 -6
  67. package/.bkit/core/workflows/bkit-build.md +59 -17
  68. package/.bkit/core/workflows/bkit-debug.md +64 -20
  69. package/.bkit/core/workflows/bkit-design.md +83 -28
  70. package/.bkit/core/workflows/bkit-plan.md +61 -20
  71. package/.bkit/core/workflows/bkit-ship.md +48 -18
  72. package/.bkit/shared/.bkit/.env.example +8 -0
  73. package/.bkit/shared/.claude/settings.json +3 -1
  74. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  75. package/.bkit/shared/.cursor/mcp.json +11 -4
  76. package/.bkit/shared/.mcp.json +11 -4
  77. package/.bkit/shared/.opencode/opencode.json +2 -0
  78. package/.bkit/shared/docs/deployments.md +6 -7
  79. package/.bkit/shared/docs/security.md +1 -1
  80. package/.bkit/shared/docs/testing.md +13 -5
  81. package/.bkit/templates/.github/renovate.json5 +1 -1
  82. package/.bkit/templates/.github/workflows/bkit-ci.yml +21 -115
  83. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  84. package/.bkit/templates/.husky/pre-commit +4 -4
  85. package/.bkit/templates/.husky/pre-push +107 -18
  86. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  87. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  88. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  89. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  90. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  91. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  92. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  93. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  94. package/CHANGELOG.md +67 -1
  95. package/README.md +16 -6
  96. package/dist/checks/after/auth.js +81 -45
  97. package/dist/checks/after/ci-yml.js +0 -1
  98. package/dist/checks/after/github.js +41 -76
  99. package/dist/checks/after/index.js +2 -7
  100. package/dist/checks/after/tools.js +1 -1
  101. package/dist/checks/before/env.js +24 -17
  102. package/dist/checks/before/mcp.js +4 -2
  103. package/dist/checks/tips/catalogue.js +14 -2
  104. package/dist/checks/tips/index.js +4 -2
  105. package/dist/cli.js +7 -5
  106. package/dist/commands/ci/ci.js +100 -0
  107. package/dist/commands/install/uninstall.js +42 -0
  108. package/dist/commands/workflow/fids.js +22 -15
  109. package/dist/commands/workflow/issues.js +53 -61
  110. package/dist/commands/workflow/ledgers.js +26 -11
  111. package/dist/commands/workflow/prs.js +3 -1
  112. package/dist/commands/workflow/repo.js +6 -0
  113. package/dist/commands/workflow/roadmap.js +3 -1
  114. package/dist/commands/workflow/steps.js +2 -2
  115. package/dist/commands/workflow/workflows.js +9 -4
  116. package/dist/commands/workflow/worktrees.js +74 -13
  117. package/dist/install/manifest.js +30 -10
  118. package/dist/install/modules/cloud.js +3 -1
  119. package/dist/install/modules/core.js +157 -5
  120. package/dist/install/modules/opencode.js +6 -0
  121. package/dist/install/write.js +26 -2
  122. package/dist/render/trackers.js +34 -20
  123. package/dist/shared/egress.js +6 -0
  124. package/dist/shared/settings.js +59 -7
  125. package/package.json +14 -3
@@ -13,18 +13,26 @@ import fs from "node:fs";
13
13
  import os from "node:os";
14
14
  import path from "node:path";
15
15
  import { fileURLToPath } from "node:url";
16
- import { choosePushBase, newestRunSha } from "./resolve-push-base.mjs";
16
+ import {
17
+ choosePushBase,
18
+ newestRunSha,
19
+ parseArgs,
20
+ repoFromRemoteUrl,
21
+ } from "./resolve-push-base.mjs";
17
22
 
18
23
  const SCRIPT = fileURLToPath(new URL("./resolve-push-base.mjs", import.meta.url));
19
24
 
20
- /** Run the script with fake `gh` / `git` binaries first on PATH. */
21
- function runWithFakes({ gh, git }) {
25
+ /** Run the script with fake `gh` / `git` binaries first on PATH; `gh` calls land in gh.log. */
26
+ function runWithFakes({ gh, git, args = [], env = {} }) {
22
27
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "push-base-"));
23
28
  try {
24
- fs.writeFileSync(path.join(dir, "gh"), `#!/bin/sh\n${gh}\n`, { mode: 0o755 });
29
+ const ghLog = path.join(dir, "gh.log");
30
+ fs.writeFileSync(path.join(dir, "gh"), `#!/bin/sh\necho "$*" >> "${ghLog}"\n${gh}\n`, {
31
+ mode: 0o755,
32
+ });
25
33
  fs.writeFileSync(path.join(dir, "git"), `#!/bin/sh\n${git}\n`, { mode: 0o755 });
26
34
  const sourceFile = path.join(dir, "source");
27
- const r = spawnSync(process.execPath, [SCRIPT], {
35
+ const r = spawnSync(process.execPath, [SCRIPT, ...args], {
28
36
  encoding: "utf8",
29
37
  env: {
30
38
  ...process.env,
@@ -33,10 +41,12 @@ function runWithFakes({ gh, git }) {
33
41
  BRANCH: "dev",
34
42
  BEFORE_SHA: "b".repeat(40),
35
43
  SOURCE_FILE: sourceFile,
44
+ ...env,
36
45
  },
37
46
  });
38
47
  const source = fs.existsSync(sourceFile) ? fs.readFileSync(sourceFile, "utf8").trim() : "";
39
- return { status: r.status, stdout: r.stdout.trim(), source };
48
+ const ghCalls = fs.existsSync(ghLog) ? fs.readFileSync(ghLog, "utf8") : "";
49
+ return { status: r.status, stdout: r.stdout.trim(), stderr: r.stderr, source, ghCalls };
40
50
  } finally {
41
51
  fs.rmSync(dir, { recursive: true, force: true });
42
52
  }
@@ -136,5 +146,92 @@ test("a green ancestor run reports last-green-run as the source", () => {
136
146
  assert(r.source === "last-green-run", r.source);
137
147
  });
138
148
 
149
+ test("a run list that could not be read is named in the source", () => {
150
+ const r = choosePushBase({
151
+ lastGreenSha: "",
152
+ beforeSha: BEFORE,
153
+ isAncestor: ancestors(),
154
+ lookupFailed: true,
155
+ });
156
+ assert(r.base === BEFORE, r.base);
157
+ assert(r.source === "event-before (run lookup failed)", r.source);
158
+ });
159
+
160
+ test("local mode names origin/<branch> as the fallback", () => {
161
+ const r = choosePushBase({
162
+ lastGreenSha: GREEN,
163
+ beforeSha: BEFORE,
164
+ isAncestor: ancestors(BEFORE),
165
+ fallback: "origin/dev",
166
+ });
167
+ assert(r.source === "origin/dev (last green run is not an ancestor)", r.source);
168
+ });
169
+
170
+ test("owner/repo comes out of https, ssh and scp-style remote URLs", () => {
171
+ assert(repoFromRemoteUrl("https://github.com/o/r.git") === "o/r", "https .git");
172
+ assert(repoFromRemoteUrl("https://github.com/o/r") === "o/r", "https");
173
+ assert(repoFromRemoteUrl("git@github.com:o/r.git\n") === "o/r", "scp");
174
+ assert(repoFromRemoteUrl("ssh://git@github.com/o/r.git") === "o/r", "ssh");
175
+ assert(repoFromRemoteUrl("") === "", "empty");
176
+ assert(repoFromRemoteUrl(undefined) === "", "missing");
177
+ });
178
+
179
+ test("--local, --branch and --head are read from argv", () => {
180
+ const a = parseArgs(["--local", "--branch=main", `--head=${GREEN}`]);
181
+ assert(a.local && a.branch === "main" && a.head === GREEN, JSON.stringify(a));
182
+ const ci = parseArgs([]);
183
+ assert(!ci.local && ci.branch === "" && ci.head === "", JSON.stringify(ci));
184
+ });
185
+
186
+ test("CI mode: an unreadable run list falls back to event.before and says so", () => {
187
+ const r = runWithFakes({ gh: "echo 'HTTP 401' >&2; exit 1", git: "exit 0" });
188
+ assert(r.status === 0 && r.stdout === "b".repeat(40), JSON.stringify(r));
189
+ assert(r.source === "event-before (run lookup failed)", r.source);
190
+ });
191
+
192
+ // Local mode: origin's URL gives the repo, origin/dev the before-sha; ancestry is tested
193
+ // against the pushed commit only ($4 of `git merge-base --is-ancestor <sha> <head>`).
194
+ const ORIGIN = "d".repeat(40);
195
+ const PUSHED = "e".repeat(40);
196
+ const LOCAL_GIT = `case "$1" in
197
+ remote) echo "git@github.com:me/app.git" ;;
198
+ rev-parse) echo "${ORIGIN}" ;;
199
+ merge-base) [ "$4" = "${PUSHED}" ] && exit 0; exit 1 ;;
200
+ *) exit 2 ;;
201
+ esac`;
202
+ const LOCAL_ARGS = ["--local", "--branch=dev", `--head=${PUSHED}`];
203
+ const NO_CI_ENV = { REPO: "ci/repo", BEFORE_SHA: "f".repeat(40) };
204
+
205
+ test("local mode: last green run is an ancestor of --head → that run's head", () => {
206
+ const r = runWithFakes({ gh: RUNS, git: LOCAL_GIT, args: LOCAL_ARGS, env: NO_CI_ENV });
207
+ assert(r.status === 0 && r.stdout === "a".repeat(40), JSON.stringify(r));
208
+ assert(r.source === "last-green-run", r.source);
209
+ assert(r.ghCalls.includes("repos/me/app/actions/workflows/"), r.ghCalls);
210
+ assert(r.ghCalls.includes("branch=dev&event=push&status=success"), r.ghCalls);
211
+ });
212
+
213
+ test("local mode: ancestry is tested against --head, not HEAD", () => {
214
+ const r = runWithFakes({
215
+ gh: RUNS,
216
+ git: LOCAL_GIT,
217
+ args: ["--local", "--branch=dev", `--head=${"9".repeat(40)}`],
218
+ });
219
+ assert(r.stdout === ORIGIN, r.stdout);
220
+ assert(r.source === "origin/dev (last green run is not an ancestor)", r.source);
221
+ });
222
+
223
+ test("local mode: gh fails → origin/dev, the reason on stderr, env REPO / BEFORE_SHA unused", () => {
224
+ const r = runWithFakes({
225
+ gh: "echo 'gh: not logged in' >&2; exit 4",
226
+ git: LOCAL_GIT,
227
+ args: LOCAL_ARGS,
228
+ env: NO_CI_ENV,
229
+ });
230
+ assert(r.status === 0 && r.stdout === ORIGIN, JSON.stringify(r));
231
+ assert(r.source === "origin/dev (run lookup failed)", r.source);
232
+ assert(r.stderr.includes("gh: not logged in"), r.stderr);
233
+ assert(r.ghCalls.includes("repos/me/app/"), r.ghCalls);
234
+ });
235
+
139
236
  console.log(`\n${passed} passed, ${failed} failed`);
140
237
  process.exit(failed > 0 ? 1 : 0);
@@ -1,5 +1,7 @@
1
1
  #!/usr/bin/env bash
2
- # Example. Paste at the end of your .husky/pre-push, below the bkit lines, and own it.
2
+ # Example. Copy to scripts/graphify/ and own it. The bkit .husky/pre-push template runs it
3
+ # above the gates, so a stale register blocks in ~30s, not after the full gate; an older hook
4
+ # copy lacks that call → re-copy the "Capability register" block from the template.
3
5
  # bkit install does not write this file and does not overwrite a copy.
4
6
  #
5
7
  # Capability register current on dev. BLOCKS a push to dev when docs/capabilities.md is not
@@ -171,7 +171,7 @@ require_graph() {
171
171
  # and in CI (installs `$(bash scripts/graphify/bkit-graphify.sh spec)`). Another release draws
172
172
  # different edges → drift no one else can reproduce. PyPI `graphifyy`, CLI `graphify`.
173
173
  # renovate: datasource=pypi depName=graphifyy
174
- GRAPHIFY_SPEC="graphifyy[sql]==0.9.50"
174
+ GRAPHIFY_SPEC="graphifyy[sql]==0.9.70"
175
175
  if [ "${1:-}" = "spec" ]; then
176
176
  printf '%s\n' "$GRAPHIFY_SPEC"
177
177
  exit 0
@@ -12,9 +12,12 @@
12
12
  //
13
13
  // Default paths: `.agents`, `docs`, `README.md`. A directory walk skips `skills/` trees (vendored)
14
14
  // and `docs/audits/` + `docs/plans/` (records, kept as written); a file named explicitly is always
15
- // processed. Tables inside fenced code blocks (``` / ~~~) and tables already wrapped are skipped.
15
+ // processed. Tables inside fenced code blocks (``` / ~~~), inside `<!-- -->` comment blocks, and
16
+ // already wrapped are skipped.
16
17
  // `--check` writes nothing and exits 1 if any file would change — use it as a gate.
17
- // Exit 1 also on table damage escaping cannot repair (see auditText), with or without --check.
18
+ // Exit 1 also on table damage escaping cannot repair (see auditText), with or without --check —
19
+ // except in the record trees, where the damage is printed as a warning: a record holds text quoted
20
+ // from elsewhere (issue comments, CI logs), so nobody can fix it there.
18
21
 
19
22
  import fs from "node:fs";
20
23
  import path from "node:path";
@@ -28,6 +31,8 @@ const INLINE_CODE = /`[^`\n]*`/g;
28
31
  const DEFAULT_ROOTS = [".agents", "docs", "README.md"];
29
32
  // Record trees: written once, never reformatted.
30
33
  const RECORD_DIRS = ["docs/audits", "docs/plans"];
34
+ const relTo = (root, p) => path.relative(root, path.resolve(root, p)).split(path.sep).join("/");
35
+ const isRecord = (r) => RECORD_DIRS.some((d) => r === d || r.startsWith(`${d}/`));
31
36
 
32
37
  const stripNl = (line) => line.replace(/\n$/, "");
33
38
  const leadingSpaces = (line) => /^ */.exec(line)[0];
@@ -85,25 +90,32 @@ function normalizeSeparator(line) {
85
90
  return `${leadingSpaces(line)}| ${cells.join(" | ")} |${nl}`;
86
91
  }
87
92
 
88
- // ``` / ~~~ fences across a line walk. Shared by processText and auditText so they never disagree:
89
- // a table inside a fence is illustrative text, neither rewritten nor reported.
90
- class FenceTracker {
91
- inFence = false;
93
+ // ``` / ~~~ fences and `<!-- -->` comment blocks across a line walk. Shared by processText and
94
+ // auditText so they never disagree: a table inside either is illustrative or hidden text, neither
95
+ // rewritten nor reported. A comment block follows CommonMark's HTML-block rule: it opens on a line
96
+ // starting with `<!--` and runs to the first line containing `-->`, so a one-line comment such as
97
+ // `<!-- prettier-ignore -->` hides nothing below it. Inserting that one-liner inside an open
98
+ // comment would close the comment early and expose everything after it.
99
+ class OpaqueBlockTracker {
92
100
  marker = "";
93
101
 
94
- // True when `line` opens, sits inside, or closes a fence.
102
+ // True when `line` opens, sits inside, or closes a fence or a comment block.
95
103
  feed(line) {
96
104
  const s = line.trimStart();
97
- if (!this.inFence) {
98
- if (s.startsWith("```") || s.startsWith("~~~")) {
99
- this.inFence = true;
100
- this.marker = s.startsWith("```") ? "```" : "~~~";
101
- return true;
102
- }
103
- return false;
105
+ if (this.marker) {
106
+ const closes = this.marker === "-->" ? line.includes("-->") : s.startsWith(this.marker);
107
+ if (closes) this.marker = "";
108
+ return true;
109
+ }
110
+ if (s.startsWith("```") || s.startsWith("~~~")) {
111
+ this.marker = s.slice(0, 3);
112
+ return true;
104
113
  }
105
- if (s.startsWith(this.marker)) this.inFence = false;
106
- return true;
114
+ if (s.startsWith("<!--")) {
115
+ if (!s.slice(4).includes("-->")) this.marker = "-->";
116
+ return true;
117
+ }
118
+ return false;
107
119
  }
108
120
  }
109
121
 
@@ -112,7 +124,7 @@ const linesWithEnds = (src) => src.match(/[^\n]*\n|[^\n]+$/g) ?? [];
112
124
  export function processText(src) {
113
125
  const lines = linesWithEnds(src);
114
126
  const out = [];
115
- const fence = new FenceTracker();
127
+ const fence = new OpaqueBlockTracker();
116
128
  let i = 0;
117
129
  while (i < lines.length) {
118
130
  const line = lines[i];
@@ -158,7 +170,7 @@ export function processText(src) {
158
170
  // Run on the POST-format text, so nothing escaping already fixed is reported twice.
159
171
  export function auditText(src) {
160
172
  const lines = src.split("\n");
161
- const fence = new FenceTracker();
173
+ const fence = new OpaqueBlockTracker();
162
174
  const problems = [];
163
175
  let i = 0;
164
176
  while (i < lines.length) {
@@ -202,13 +214,9 @@ export function auditText(src) {
202
214
  // Markdown files under the given roots. Walks skip `skills/` trees (third-party content: any file
203
215
  // whose PARENT dirs include `skills`, so a file merely named skills.md is kept) and the record trees.
204
216
  export function collectTargets(args, root = process.cwd()) {
205
- const rel = (p) => path.relative(root, path.resolve(root, p)).split(path.sep).join("/");
206
217
  const walked = (p) => {
207
- const r = rel(p);
208
- return (
209
- !path.dirname(r).split("/").includes("skills") &&
210
- !RECORD_DIRS.some((d) => r === d || r.startsWith(`${d}/`))
211
- );
218
+ const r = relTo(root, p);
219
+ return !path.dirname(r).split("/").includes("skills") && !isRecord(r);
212
220
  };
213
221
  const files = [];
214
222
  for (const arg of args.length ? args : DEFAULT_ROOTS) {
@@ -237,6 +245,7 @@ export function main(argv, { root = process.cwd(), log = console.log } = {}) {
237
245
  let changed = 0;
238
246
  const unformatted = [];
239
247
  const problems = [];
248
+ const warnings = [];
240
249
  for (const file of targets) {
241
250
  const abs = path.resolve(root, file);
242
251
  const src = fs.readFileSync(abs, "utf8");
@@ -249,7 +258,8 @@ export function main(argv, { root = process.cwd(), log = console.log } = {}) {
249
258
  log(`updated: ${file}`);
250
259
  }
251
260
  }
252
- for (const p of auditText(next)) problems.push([file, ...p]);
261
+ const found = isRecord(relTo(root, file)) ? warnings : problems;
262
+ for (const p of auditText(next)) found.push([file, ...p]);
253
263
  }
254
264
  if (checkOnly) {
255
265
  for (const file of unformatted) log(`needs formatting: ${file}`);
@@ -257,15 +267,25 @@ export function main(argv, { root = process.cwd(), log = console.log } = {}) {
257
267
  } else {
258
268
  log(`\n${changed}/${targets.length} files updated`);
259
269
  }
270
+ const report = (list) => {
271
+ for (const [file, lineNo, kind, detail] of list) {
272
+ log(` ${file}:${lineNo} [${kind}]`);
273
+ log(` ${detail}`);
274
+ }
275
+ };
260
276
  if (problems.length) {
261
277
  log(
262
278
  `\n${problems.length} table defect(s) escaping cannot repair — a pipe in plain cell\n` +
263
279
  "prose is indistinguishable from a column delimiter, so these need a human:\n",
264
280
  );
265
- for (const [file, lineNo, kind, detail] of problems) {
266
- log(` ${file}:${lineNo} [${kind}]`);
267
- log(` ${detail}`);
268
- }
281
+ report(problems);
282
+ }
283
+ if (warnings.length) {
284
+ log(
285
+ `\nWARN: ${warnings.length} table defect(s) in records (${RECORD_DIRS.join(", ")}) — kept as\n` +
286
+ "written, not a failure:\n",
287
+ );
288
+ report(warnings);
269
289
  }
270
290
  return problems.length || unformatted.length ? 1 : 0;
271
291
  }
package/CHANGELOG.md CHANGED
@@ -6,7 +6,73 @@ Format: `## [version] — YYYY-MM-DD`
6
6
 
7
7
  ---
8
8
 
9
- ## [Unreleased]
9
+ ## [5.5.1] — 2026-10-22
10
+
11
+ ### Breaking Changes
12
+
13
+ - **BREAKING — the GitHub board setting is `bkit.github.project`, the board's URL.** It sits under `bkit.github` beside `progress` and `review`, the same shape as `bkit.linear` and `bkit.jira`. Paste the board URL from the browser: `"github": { "project": "https://github.com/orgs/<org>/projects/<number>" }`, or `/users/<login>/…` for a personal board; a trailing `/views/<n>` is fine. Status is set by option name, `In progress` and `In review` by default (the names GitHub's board templates use); set `bkit.github.progress` / `review` if your board names them differently. You no longer look up a Status field id or option ids. Personal boards now work: the old setting always asked for an organization's board, so a personal board failed with a 404. `bkit upgrade` moves an old `bkit.githubProject` for you; if it logs that an option id has no name, set that name by hand. The `github-project-status-field-id-format` advisory is gone with the field id. `bkit issues labels --board` prints two payloads, `addItem` and `updateItem`; `listItems` is gone, and `boardSkipped` can be `project-url-invalid`. `bkit repo info` prints `trackerBoard`.
14
+
15
+ ### Added
16
+
17
+ - **A local stack lock keeps worktrees off each other's local services.** Every worktree of a repo shares each local service whose names and ports come from the repo's config (a Docker database, an emulator), so a reset from one worktree wiped the data under another worktree's test run. Copy the new template `.bkit/templates/scripts/ci/bkit-local-stack-lock.sh` to `scripts/ci/`, wrap the `package.json` scripts that start, reset or stop the stack in its `run` mode, and source it in local runners that test against the stack. A second run waits and names the run holding the stack; the lock frees itself within a second of its run ending, however the run ends; CI skips it. The new `.agents/rules.md` rule `Shared local stack` tells agents to use those scripts, never the raw command. Setup: `.bkit/templates.md` § Local stack lock.
18
+ - **`.agents/rules.md` gets a `Project Settings` section for where your services live.** A table at the end of the file holds the identifiers agents pass to MCP servers and CLIs: the GitHub repo and project board, Sentry org and project, Supabase project refs, Vercel team and project. Agents read the file every session, so they no longer have to guess or ask. It is reference only and changes no workflow, gate or permission. New installs get the section with commented example rows; in an existing install, add `## Project Settings` after your `Project Rules` and fill in a `Service | Setting | Value` table. Put non-secret identifiers only; tokens stay in env files.
19
+
20
+ - **On a push to `dev`, the pre-push slop scan compares against the same commit CI does.** CI's slop scan on a `dev` push compares against the head of the last green CI run on `dev`; pre-push compared against the merge-base with `origin/dev`. Once a red push had landed a slop finding on `dev`, every later local check passed while CI stayed red. `scripts/ci/lanes/resolve-push-base.mjs` gains a local mode, `--local --branch=dev --head=<pushed sha>`: it reads the repo from `origin`, uses `origin/dev` where CI uses `event.before`, and tests ancestry against the pushed commit. The `.husky/pre-push` template runs it on a `dev` push, exports the result as `SLOP_BASE_REF` (which `bkit ci slop` already reads), and prints the base it chose and why. When `gh` cannot list the runs, the hook prints a loud warning and uses `origin/dev`. Other branches, and repos without the script, are unchanged. CI mode picks the same base as before; when the run lookup fails, its logged source now reads `event-before (run lookup failed)`. To adopt: re-copy `scripts/ci/lanes/resolve-push-base.mjs` and its `.test.mjs` from `.bkit/templates/scripts/ci/lanes/`, and paste the `Slop base on a dev push` block from the template into your `.husky/pre-push`, after `pnpm bkit check`. A pre-push check of your own that should diff against CI's base (migration immutability, say) can read `SLOP_BASE_REF`. (#653)
21
+
22
+ ### Changed
23
+
24
+ - **`.bkit/prompts.md` § Orchestrators says how to set up the Claude Code session an orchestrator runs in.** Subagents carry their own `model:` and `effort:`, but `/bkit-*` orchestrators run on whatever the session runs. The new table says to launch on `claude-opus-5-5` for `/bkit-design`, `/bkit-plan` and `/bkit-debug` and on `claude-sonnet-5-5` for `/bkit-build` and `/bkit-ship`, and to leave effort alone: medium is already Claude Code's default for the 5.5 models, and a top-level `effortLevel` in `~/.claude/settings.json` does not reach them. It shows how to change effort for one session or one repo, and when to open `claude-fable-5-1` by hand: to refine an idea before `/bkit-design`, and to work a bug from the debug handover when `/bkit-debug` is stuck on it. Two warnings: `CLAUDE_CODE_EFFORT_LEVEL` flattens every subagent to one level, and a `maxEffortLevel` below `xhigh` caps the `xhigh` agents. bkit ships no `effortLevel`; nothing to do in your repo.
25
+ - **Both docs-sync agents run on Sonnet 5.5 at `high`.** On Claude Code, `@bkit-ship-update-docs` moves from `claude-opus-5-5` to `claude-sonnet-5-5`, at about half the cost on every ship. `@bkit-utility-update-documentation` moves from `medium` to `high`, because it checks every doc against the code with no feature diff to narrow the search. The ship agent follows on the other tools, as every agent follows its Claude tier: `composer-2.5` on Cursor and `gpt-5.6-terra` on Codex (Antigravity and opencode already pinned the same model for both tiers). `bkit upgrade` picks it up.
26
+ - **The `.husky/pre-push` template runs its fast checks before the gates, and runs the capability register check itself.** `bkit check` used to wait for the full gate, and the register check was a snippet you pasted at the end, so a drifted install or a stale `docs/capabilities.md` blocked a push only after 10-15 minutes of lint and tests had passed. Now both run straight after the CI-token guards and stop the push in seconds (the register check in ~30s). The template calls `scripts/graphify/bkit-graph-pre-push.sh` when you have copied it, and skips it on a min push; without the script nothing changes. In your adopted copy, move `pnpm bkit check` and any register block above the `bkit:gate*` block, or re-copy the `Fast blocking checks` and `Capability register` blocks from the template. Other quick extras that can block (a few seconds, needing nothing the gates build) belong there too.
27
+ - **A workflow's `## bkit Tips` bolds the star and silence questions like each tip's title.** `**Do you like bkit?**` and `**Want to silence these tips?**` (or `this tip`) now open their lines in bold, so all three paragraphs read the same. Bare `bkit tips` and `--all`, which are plain terminal lists, are unchanged.
28
+ - **The `bkit-ci.yml` template drops `Check Tree Cache`.** It never skipped anything: a feature PR's files have never been pushed to `dev` or the default branch, and a release PR runs in mirror mode with every lane off. The template's lanes run their steps unconditionally, `bkit-tests-unit` loses its `cache_skip` output, and `check-capstone.mjs` drops the `<LANE>_CACHE_SKIP` exemption, so a lane that ran 0 tests fails the capstone whatever that variable says. In your adopted copy, delete the `Check Tree Cache` step from each lane, `steps.cache.outputs.skip != 'true'` from every `if:` (and an `if:` it leaves empty), each lane's `cache_skip` output, the capstone's `*_CACHE_SKIP` variables, and `scripts/ci/lanes/check-tree-cache.mjs` with its `.test.mjs`. A lane's job-level `actions: read` was for the cache only; keep `contents: read` and `pull-requests: write`. Then re-copy `scripts/ci/check-capstone.mjs` and its `.test.mjs`. Until you do, a copy that keeps the step still works; it just never skips.
29
+ - **`bkit worktrees setup` starts a new feature branch from local `dev` when it holds unpushed commits.** When local `dev` is ahead of `origin/dev` and nothing else differs, the branch is cut from local `dev`, and a resumed worktree rebases onto it, so the worktree has those commits; the command says how many and reminds you to push `dev` before the feature PR. When the two have diverged, it stays on `origin/dev` and says so. The output gains `baseRef` (`dev` or `origin/dev`), and `baseSha` is the merge base with it.
30
+ - **`bkit worktrees setup` runs `direnv allow` in the new worktree.** It does so only when the worktree's `.envrc` is byte-identical to the main checkout's, so the worktree gets the trust you already gave and nothing more. A differing `.envrc`, or direnv missing or failing, is reported and never stops setup. The output gains `direnvAllowed`.
31
+
32
+ ### Fixed
33
+
34
+ - **The `bkit-insert-ignore.mjs` template leaves tables inside multi-line `<!-- -->` comments alone.** It treated a commented-out table as a real one and offered to insert `<!-- prettier-ignore -->` inside the comment, which would close the comment early and show the rest of it on the page; `--check` failed on such a table and blocked the push. The `Project Settings` example rows that new installs get in `.agents/rules.md` are such a table. Tables in a comment are now skipped like tables in a code fence. Re-copy `scripts/prettier/bkit-insert-ignore.mjs` from `.bkit/templates/scripts/prettier/`.
35
+ - **`.agents/rules.md` `New worktree` names the real setting.** It said `bkit.worktreeCopy`; the `package.json` key is `bkit.worktree.copy`. The rule also says `bkit worktrees setup` does the copy, the install and `direnv allow` itself.
36
+
37
+ ---
38
+
39
+ ## [5.5.0] — 2026-10-21
40
+
41
+ ### Breaking Changes
42
+
43
+ - **BREAKING — `bkit issues labels` and `bkit workflows fail` print `trackerState`, not `linearState`.** The field holds the state the issue moves to on Linear or Jira, and is `null` on GitHub and `none`. A script or custom workflow reading `linearState` gets nothing until it reads `trackerState`. (#60)
44
+
45
+ ### Added
46
+
47
+ - **`@bkit-utility-update-tracker` keeps open issues in line with the tracker rules.** Run it on demand. It shortens titles over 70 characters, sets type and `next:*` labels, board status, priority, size, milestone, parent and blocked-by links. Priority and size come from the newest issue prioritisation audit report, then from that audit's ranking and size rules. It never creates, closes or comments on issues, never touches `bkit:*` labels and never removes a link; new milestones and parent issues are suggestions only. (#647)
48
+ - **The roadmap and audits point at the related utilities.** `docs/roadmap.md`'s generated header lists the `@bkit-utility-update-*` utilities with one line each, refreshed on every fold. `@bkit-audit-generate` ends every run with the same line, word for word. (#647)
49
+ - **`bkit-cloud.yml`'s claude job runs without a stored API key.** Set the `ANTHROPIC_FEDERATION_RULE_ID` and `ANTHROPIC_ORGANIZATION_ID` repo variables from a Claude Console federation rule and leave the `ANTHROPIC_API_KEY` secret unset: `claude-code-action` trades the job's GitHub OIDC token for a Claude API token that lasts minutes. A set key still wins over federation. The template's gate step is now `Check runner credentials` and the claude step passes the federation inputs; re-copy your adopted `.github/workflows/bkit-cloud.yml` to use them. `bkit check` stops asking for the key once federation is set up, and flags a key that shadows federation (`anthropic-api-key-shadows-federation`) and an adopted copy too old to pass the inputs (`anthropic-federation-template-stale`). Setup: `.bkit/cloud.md` § Claude — workload identity federation. (#644)
50
+
51
+ - **A push that changes only plan logs and ledgers runs `bkit:gate:min`.** The `.husky/pre-push` template asks `bkit ci min-push --ref=<sha>…` whether every changed file matches `bkit.minPushPaths` (`package.json`; default `docs/plans/**`, `docs/*.jsonl`, `.bkit/*.jsonl`; `[]` = off). If so, the new seeded `bkit:gate:min` (format, prose, slop delta) replaces the full gate, and `MIN_PUSH=1` lets slow repo extras skip. Files decide, never `[skip ci]`; any doubt runs the full gate. A push to `dev` / `main` whose skip-CI-token commit changes any other file is blocked: GitHub would skip CI for the whole push. Setup tip `min-push`; steps in `.bkit/templates.md` § Git hooks. (#645)
52
+ - **Jira is a tracker.** `bkit install --tracker=jira` wires the Atlassian MCP server under the key `jira` for Claude, Cursor and opencode, authenticating with `BKIT_JIRA_API_TOKEN` as a Bearer token. Every workflow and prompt drives a Jira issue as it does a GitHub or Linear one: it finds the key (also from a `/browse/KEY` link), reads it, writes labels then status, posts step comments (split above 32,767 characters), checks open blockers and searches related issues. Jira moves status by transition, so each workflow's Tracker header lists the issue's transitions and takes the one whose target status matches, else logs it as Unapplied. Issue keys mint FIDs like Linear ones (`MBA-7` → `mba-7-slug`). `bkit check` knows the token and the server, and the `tracker-setup-jira` advisory names the admin setting and the `package.json` keys to set. Jira repos run locally only: `bkit-cloud.yml` stops before any work unless `bkit.issueTracker` is `github` or unset. Setup: `.bkit/trackers.md` § jira — setup and notes. (#60)
53
+ - **Audits report to one standing parent issue per template.** Run without an issue and with a tracker wired, `@bkit-audit-generate` searches for that template's audit parent and posts its summary there; with none, it suggests one (title, body, run line) and keeps the summary for the new parent's first comment. Issues filed from an audit's suggestions are always sub-issues of that parent. The agent still never creates, closes or relabels issues; it gains one read-only search tool per tracker. Shape: `.bkit/trackers.md`. (#627)
54
+
55
+ ### Changed
56
+
57
+ - **The pre-push hook runs the integration tier once you declare its gate.** The `.husky/pre-push` template runs `bkit:gate:static-unit-integration` when package.json declares it, else `bkit:gate:static-unit` as before. Integration runs on push, never on commit; it may start local services such as a database in Docker, while E2E, `@live` and anything that reaches a deployed service stay in CI. A copied hook is yours: to pick this up, replace the `pnpm bkit:gate:static-unit` line in your `.husky/pre-push` with the template's `elif grep …` block, or call your integration gate there directly.
58
+ - **`bkit install`, `bkit check` and `bkit upgrade` flag a check that runs twice.** The new `gate-commit-repeats-push` advisory names any script `bkit:gate:format` (pre-commit) runs that the push gate runs again, such as a whole-repo prose lint. `.bkit/templates.md` and `docs/testing.md` now also say that `pnpm test` is the unit tier only: a unit config that matches `*.integration.test.*` files, or a unit gate that calls both `pnpm test` and a coverage run, runs the same tests twice on every push.
59
+ - **The `/bkit-design` interview ends by confirming a draft acceptance scenario.** The last round shows a draft Narrative, Success Criteria, Key Edge Cases and Process Sketch, built from the prompt, the issue and its comments, and every answer so far. It asks you to confirm or refine the parts it had to guess, and counts toward the 10-round cap. The draft is saved under a `DRAFT only` label. The design starts its Acceptance Scenario from it and records each change as a Decisions row. Headless runs save the draft marked as not reviewed by a human; `grill=false` writes no draft.
60
+ - **Tracker rules cover status, links, priority and size.** `.agents/rules.md` `Tracker issue settings` now also requires project status, parent and blocked-by links. Priority and size follow the issues audit's `Ranking Rules` and new `Size Scale` section, and blocked-by uses the machine-read form. The tracker rules are reordered: issue creation and settings first, then labels, comments, and tool use. (#647)
61
+ - **Agents comment on the issue at the end of every major turn.** `.agents/rules.md` `Tracker work comments` now asks for one comment per related issue whenever a turn changes files, commits, opens a PR, finds something or stops blocked, not only when a commit or PR lands. Turns that only answer a question or ask one post nothing. `/bkit-*` workflows still post their own comments.
62
+ - **The closing offers sit under a `## Suggested Replies` heading.** Phase workflow, audit and ledger-update summaries now put the plain-English offer, and in `/bkit-design` and `/bkit-plan` the one-by-one questions offer, under their own heading after the summary and above `## bkit Tips`, so they no longer read as the summary's last lines. In `.bkit/wording.md` a heading the agent shows you is its own clause, separate from the text under it: `suggested-replies-heading`, and `workflow-setup-tips-heading` split from `workflow-setup-tips-append`. `@bkit-utility-update-documentation` now has shell access and shows `## bkit Tips` too, like the other utilities.
63
+ - **The state a workflow moves an issue to comes from config, and Linear settings live in one object.** `bkit.linear` and `bkit.jira` each name a `progress` and a `review` state (Linear defaults `started` / `In Review`, Jira `In Progress` / `In Review`). `bkit.linear` holds `team`, `project`, `progress` and `review`; `install` and `upgrade` move an old `bkit.linearTeam` to `bkit.linear.team`, and an existing `bkit.linear.team` wins (`docs/migrations.md`). `bkit repo info` prints `trackerTeam`, `trackerProject` and `trackerSite`, and Linear's related-issue search narrows to `bkit.linear.project` when set. (#60)
64
+ - **The shipped Claude settings no longer allow `mcp__claude_ai_Linear__*`.** No workflow calls the claude.ai Linear connector; they all use the project `linear` server. Existing installs keep the row until you delete it. (#60)
65
+ - **The graphify template pins 0.9.70.** `.bkit/templates/scripts/graphify/bkit-graphify.sh` and the Renovate comment that tracks it now name `graphifyy[sql]==0.9.70`. If you adopted the script, update your copy's `GRAPHIFY_SPEC`, install that release, and run `pnpm graph:refresh`: another release draws different edges, so the register drifts.
66
+ - **`git stash clear` and `git -C <dir> reset --hard` ask first on every host.** `git stash clear` deletes every stash and joins `git stash drop` in the ask tier and in the agents' destructive-git list. Claude and opencode now also match `reset --hard` after git global options, as the parsed hosts already did.
67
+ - **The `bkit-ci.yml` template's cache skips pull requests only, and matches files instead of commit IDs.** `Check SHA Cache` is now `Check Tree Cache`, backed by the new template `scripts/ci/lanes/check-tree-cache.mjs` (copy it with its `.test.mjs`). A pull request lane skips when the PR's files are exactly the files of a push run whose same lane passed in the last 7 days. The old step compared commit IDs, and a pull request run tests a merge commit no earlier run ever had, so it never skipped a pull request. It could skip a push run, though; a push run now always runs the suite. `[force build]` / `[force cache]` in the PR title still run it. Re-copy the step into each lane of your adopted `.github/workflows/bkit-ci.yml`; without the script the step runs the suite. Details: `docs/deployments.md` § Pull request tree cache.
68
+
69
+ ### Fixed
70
+
71
+ - **Linear workflow updates work on a default Linear team.** Linear rejects an entire `save_issue` call when one state or label name doesn't exist on the team, valid fields included, and a default team has no `In Review` state and no `bkit:*` labels. As a result, every phase change failed until someone created them by hand, and a Failure Path never added `bkit:failed`. Now the workflows create each label they add with `save_issue_label` before using it, then write labels and state in separate calls. A phase start sets the state type `started`, which every team has. A team without `In Review` keeps the issue in its started state and logs the skipped state as `Unapplied`, while `bkit:merged` / `bkit:failed` carry the hand-off. `bkit workflows fail` now prints `add`, like `bkit issues labels`. `/bkit-ship` takes its Linear states from those commands instead of naming them itself. (#646)
72
+ - **The cloud secrets checklist asks for the Linear key only on Linear repos.** A GitHub or Jira repo with only `.cursor/` was told to set it. (#60)
73
+ - **Targeted uninstalls remove the settings their module wrote.** `bkit uninstall --auto` removes `bkit.cloudAgents` and a bare `bkit uninstall --opencode` removes `bkit.opencodeProvider` / `bkit.opencodeProviders`, so `bkit check` stops printing that module's advisories.
74
+ - **`bkit check` catches a hook that lost its executable bit, and `install` / `upgrade` restore it.** Cursor runs `.cursor/hooks/bkit-preflight.sh` directly, so a lost bit broke its session-start hook while the drift gate stayed green.
75
+ - **Docs say what Cursor's guardrail hook does on a payload it cannot read.** It allows, like every other bkit hook; `failClosed` blocks only when the hook process crashes. `.bkit/providers.md` called it fail-closed.
10
76
 
11
77
  ## [5.4.0] — 2026-10-20
12
78
 
package/README.md CHANGED
@@ -32,7 +32,7 @@
32
32
 
33
33
  AI coding agents are fast, but on their own they skip what makes software safe to ship: a design someone challenged, a plan someone checked, a second pair of eyes on every change, tests that actually ran. **Vibe coding gets you a demo. Production takes a process.**
34
34
 
35
- **bkit is that process, ready-made.** Describe a feature in a GitHub or Linear issue and type one command:
35
+ **bkit is that process, ready-made.** Describe a feature in a GitHub, Linear or Jira issue and type one command:
36
36
 
37
37
  ```text
38
38
  /bkit-design ISSUE-123
@@ -106,6 +106,13 @@ Every agent in each phase, in the order it runs and what it checks: [pipeline re
106
106
 
107
107
  **Claude sets the bar, and every other tool gets the model that comes closest to it.** On every other tool, each agent runs on the model that does the same job about as well as Claude, for the least money. You don't pick: install sets each agent's model.
108
108
 
109
+ <p align="center">
110
+ <picture>
111
+ <source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-models-dark.svg">
112
+ <img alt="Change the model, not the effort. The Claude model and effort behind each of bkit's 50 agents and 5 orchestrators. Opus 5.5 at Medium: /bkit-design, /bkit-plan, /bkit-debug, 2 agents; Opus 5.5 at High: 20 agents; Opus 5.5 at Extra: 8 agents; Sonnet 5.5 at Medium: /bkit-build, /bkit-ship, 7 agents; Sonnet 5.5 at High: 8 agents; Haiku 5.5 at High: 5 agents. Fable 5.1 is never pinned: use it by hand to refine an idea before /bkit-design, and at Extra for a bug /bkit-debug is stuck on. Pick the model at launch: claude-opus-5-5 for /bkit-design, /bkit-plan, /bkit-debug; claude-sonnet-5-5 for /bkit-build, /bkit-ship. Leave the effort alone: medium is the default on the 5.5 models, every agent sets its own, and never set CLAUDE_CODE_EFFORT_LEVEL. Past High, move up a model: Extra costs more than the next model up at High. Max is for one hard problem, never routine; ultracode is a setting, not a level." src=".github/assets/bkit-models-light.svg" width="100%">
113
+ </picture>
114
+ </p>
115
+
109
116
  **How the picks are made.** Each kind of job has a bar: Claude's score on [LiveBench Agentic Coding](https://livebench.ai/#/?cats=Agentic+Coding), a public test where models fix real code in JavaScript, TypeScript and Python. For each tool, bkit takes the **cheapest model that reaches the bar**. Where nothing reaches it, the tool's best model gets the job. One model can fill two columns: on opencode, DeepSeek V4.1 Flash clears the bar for the hardest jobs, so it does the everyday jobs too, for a fraction of Claude's cost. Claude is never used on opencode, because opencode is where work goes when your Claude allowance runs out.
110
117
 
111
118
  <!-- prettier-ignore -->
@@ -129,6 +136,8 @@ Every agent in each phase, in the order it runs and what it checks: [pipeline re
129
136
  - **Ollama needs a paid plan for every column.** The free models are far below the bar or not scored.
130
137
  - **Want a different model for one agent?** On Cursor and opencode, add a row to [Model Overrides](.bkit/prompts.md#model-overrides) and run `bkit install` again. Every agent with its model and thinking depth: [`.bkit/prompts.md` § Models](.bkit/prompts.md#models).
131
138
 
139
+ **On Claude Code, each agent also sets its own effort**, so the effort you leave your session on never changes theirs. Start each `/bkit-*` command on the model the picture above shows and leave effort at the default. Session setup in full: [`.bkit/prompts.md` § Orchestrators](.bkit/prompts.md#orchestrators-slash-commands).
140
+
132
141
  <a id="why-its-different"></a>
133
142
 
134
143
  ## Why it's different
@@ -167,7 +176,7 @@ What that gets you:
167
176
  - **The fences grow with every feature.** Each build adds tests every later change has to pass. A prompt-only framework is as strict on your fiftieth feature as on your first; bkit gets stricter.
168
177
  - **What's sent back is evidence, not a verdict.** A red lane hands debug the failing logs and what changed since the last green run, so the fix starts from the actual error, not a guess.
169
178
  - **Agents look before they change anything.** Code search ([Serena](https://github.com/oraios/serena)) shows every definition and caller of the code about to change, not just lines with matching words, and [graphify](https://github.com/Graphify-Labs/graphify)'s code map shows what already exists. Fewer bad changes reach the fences at all.
170
- - **Problems are caught at the nearest fence.** Agent hooks nudge on every edit: read a file before changing it, fix the code rather than loosen a check. The pre-commit hook formats in seconds. The pre-push hook runs type checks, unit tests, the prose checker and the junk-code scanner before anything leaves your laptop. CI keeps only what can't run there: integration, end-to-end and live-site tests. Hooks, agents and CI's quick-checks lane all run the same `bkit:gate:*` scripts, so most failures show up on your machine first.
179
+ - **Problems are caught at the nearest fence.** Agent hooks nudge on every edit: read a file before changing it, fix the code rather than loosen a check. The pre-commit hook formats in seconds. The pre-push hook runs type checks, unit tests, integration tests (once you declare that gate), the prose checker and the junk-code scanner before anything leaves your laptop. CI keeps only what can't run there: end-to-end and live-site tests. Hooks, agents and CI's quick-checks lane all run the same `bkit:gate:*` scripts, so most failures show up on your machine first.
171
180
 
172
181
  The agent hooks come with install. Serena, graphify and the git hooks are [templates](#templates) you adopt. Compared with other frameworks: [agents and CI](.bkit/comparison.md#agents-and-ci).
173
182
 
@@ -199,7 +208,7 @@ How the lanes join into the one final check, and what happens on green or red: [
199
208
  <p align="center">
200
209
  <picture>
201
210
  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-context-dark.svg">
202
- <img alt="What it knows: right context, right step, written back as it learns. In your repo, bkit reads project docs at every step and updates them at ship; reads and writes lessons, decisions, postponed work and known bugs; writes designs and plans that later steps read; reads audit reports at plan and a code map at every step; keeps run state and stats at every step; adds skills at build and removes them at ship. Outside your repo, it reads and updates the GitHub or Linear issue at every step, searches related issues at design, plan and debug, searches the web at design and debug, reads CI runs and test reports at debug and ship, reads runtime platforms such as Sentry, Vercel, Supabase and Stripe at debug, and opens, fixes and merges the pull request." src=".github/assets/bkit-context-light.svg" width="100%">
211
+ <img alt="What it knows: right context, right step, written back as it learns. In your repo, bkit reads project docs at every step and updates them at ship; reads and writes lessons, decisions, postponed work and known bugs; writes designs and plans that later steps read; reads audit reports at plan and a code map at every step; keeps run state and stats at every step; adds skills at build and removes them at ship. Outside your repo, it reads and updates the GitHub, Linear or Jira issue at every step, searches related issues at design, plan and debug, searches the web at design and debug, reads CI runs and test reports at debug and ship, reads runtime platforms such as Sentry, Vercel, Supabase and Stripe at debug, and opens, fixes and merges the pull request." src=".github/assets/bkit-context-light.svg" width="100%">
203
212
  </picture>
204
213
  </p>
205
214
 
@@ -207,7 +216,7 @@ How the lanes join into the one final check, and what happens on green or red: [
207
216
 
208
217
  - **Docs that keep themselves current.** Install sets up the docs a professional project keeps: architecture, data schema, deployments, testing, security, monitoring, design system, tech stack and local setup. Agents fill them in as they work, `/bkit-ship` updates them after every feature, and [an index](.agents/docs.md) tells each agent which docs to read at each step. They stay current because the agents depend on them.
209
218
  - **Project memory agents actually read.** Four ledgers record lessons from every fix (`docs/knowledge.jsonl`), decisions and their reasons (`docs/decisions.jsonl`), work consciously postponed (`docs/deferrals.jsonl`) and known bugs (`docs/failures.jsonl`). Plan reviewers see the past bugs and postponed work closest to the new feature, debug reads the lessons first, and `/bkit-ship` checks nothing postponed was quietly dropped. Four utility agents keep them honest: they correct lessons and decisions the code has since contradicted, and close postponed work and known bugs that have already been fixed.
210
- - **Tracker issues are memory too.** Every step reads the whole tracker issue (e.g. GitHub, Linear), comments included, and adds what it did as a new comment without editing earlier ones, so the issue becomes the feature's running record. bkit skips its own comments when it reads, so agents act on what people wrote. Design, plan and debug also search your other tracker issues, closed ones included, for earlier designs, duplicate work and past incidents.
219
+ - **Tracker issues are memory too.** Every step reads the whole tracker issue (e.g. GitHub, Linear, Jira), comments included, and adds what it did as a new comment without editing earlier ones, so the issue becomes the feature's running record. bkit skips its own comments when it reads, so agents act on what people wrote. Design, plan and debug also search your other tracker issues, closed ones included, for earlier designs, duplicate work and past incidents.
211
220
  - **Outside evidence, when it's needed.** Design searches the web for feasibility. Debug pulls failed CI logs, the diff since the last green run, end-to-end reports and runtime errors. 10+ ready-made connectors cover GitHub, Sentry, Vercel, Supabase, Stripe, Expo, Playwright, Maestro, Inngest, Resend, Cloud Run, Tavily web search and Serena, each easy to customise, extend or leave out. A connector that isn't set up is reported as such, never read as "all clear".
212
221
  - **Progress lives in your repo, not a chat window.** Run state is saved after every step, so a crashed run resumes where it stopped, on any tool.
213
222
 
@@ -287,9 +296,10 @@ All templates, what each is for, and how to install them: [`.bkit/templates.md`]
287
296
 
288
297
  ### Your tracker is the control panel
289
298
 
290
- - **Every run lives on the tracker issue.** bkit reads the tracker issue (e.g. GitHub, Linear), posts progress as it goes, moves the issue along and links the pull request.
299
+ - **Every run lives on the tracker issue.** bkit reads the tracker issue (e.g. GitHub, Linear, Jira), posts progress as it goes, moves the issue along and links the pull request.
291
300
  - **Issues that start the right step.** Optional issue forms for a new idea, a well-defined change or a bug ask for what the agents read first, and each names the command to run next. A well-defined change can be the plan itself: what done looks like, the tests and the tasks.
292
301
  - **It tells you what to work on next.** `@bkit-utility-update-roadmap` reads your board and the open known bugs and postponed work from the ledgers, then writes a ranked shortlist into `docs/roadmap.md`.
302
+ - **It keeps the tracker tidy.** `@bkit-utility-update-tracker` brings open issues in line with the tracker rules: short titles, the right labels, board status, priority, size, milestone, parent and blocked-by links. It takes priorities from the latest issue prioritisation audit and suggests new milestones and parent issues, but never creates or closes an issue.
293
303
  - **See it live:** [bkit's own board](https://github.com/users/cbartens/projects/1/views/1), and the shortlist bkit ranked from it in [`docs/roadmap.md`](docs/roadmap.md).
294
304
 
295
305
  ### You stay in control
@@ -372,7 +382,7 @@ No full run, from design to merge, has taken longer than a day. Each run posts i
372
382
  **Not without your sign-off.** In the full workflows, work happens in a separate copy of the repo, goes through a pull request, must pass every test, and merges into `dev`, never `main`. Lite workflows skip the pull request and CI, which is why they're only for small, clearly safe changes.
373
383
 
374
384
  **Which issue tracker, and which code host?**
375
- GitHub Issues or Linear for the tracker. The code has to live on GitHub: pull requests, CI and cloud mode run there.
385
+ GitHub Issues, Linear or Jira for the tracker. The code has to live on GitHub: pull requests, CI and cloud mode run there.
376
386
 
377
387
  **Is this the bkit Vibecoding Kit?**
378
388
  No. [bkit Vibecoding Kit](https://github.com/popup-studio-ai/bkit-claude-code) is a separate project that shares the name. This bkit is `@cbartens/bkit` on npm, at [github.com/cbartens/bkit](https://github.com/cbartens/bkit).