@cbartens/bkit 5.5.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 (56) hide show
  1. package/.bkit/README.md +2 -2
  2. package/.bkit/core/.agents/rules.md +17 -1
  3. package/.bkit/core/.bkit/README.md +1 -1
  4. package/.bkit/core/.bkit/cloud.md +2 -2
  5. package/.bkit/core/.bkit/install.md +3 -4
  6. package/.bkit/core/.bkit/prompts.md +29 -14
  7. package/.bkit/core/.bkit/templates.md +34 -9
  8. package/.bkit/core/.bkit/trackers.md +10 -1
  9. package/.bkit/core/.bkit/workflows.md +10 -9
  10. package/.bkit/core/engine/checks/after/ci-yml.ts +0 -1
  11. package/.bkit/core/engine/checks/after/github.ts +24 -73
  12. package/.bkit/core/engine/checks/after/index.ts +0 -5
  13. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  14. package/.bkit/core/engine/checks/tips/index.ts +5 -2
  15. package/.bkit/core/engine/commands/workflow/issues.ts +26 -47
  16. package/.bkit/core/engine/commands/workflow/repo.ts +2 -0
  17. package/.bkit/core/engine/commands/workflow/worktrees.ts +91 -14
  18. package/.bkit/core/engine/install/modules/core.ts +77 -6
  19. package/.bkit/core/engine/shared/settings.ts +46 -14
  20. package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -0
  21. package/.bkit/core/prompts/bkit-design-generate.md +2 -0
  22. package/.bkit/core/prompts/bkit-plan-generate.md +5 -3
  23. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  24. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
  25. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  26. package/.bkit/core/workflows/bkit-build.md +3 -3
  27. package/.bkit/core/workflows/bkit-debug.md +3 -3
  28. package/.bkit/core/workflows/bkit-design.md +3 -3
  29. package/.bkit/core/workflows/bkit-plan.md +3 -3
  30. package/.bkit/core/workflows/bkit-ship.md +3 -3
  31. package/.bkit/shared/docs/deployments.md +5 -17
  32. package/.bkit/shared/docs/testing.md +11 -3
  33. package/.bkit/templates/.github/workflows/bkit-ci.yml +21 -83
  34. package/.bkit/templates/.husky/pre-push +48 -9
  35. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  36. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  37. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  38. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  39. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  40. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  41. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  42. package/CHANGELOG.md +30 -0
  43. package/README.md +9 -0
  44. package/dist/checks/after/ci-yml.js +0 -1
  45. package/dist/checks/after/github.js +24 -71
  46. package/dist/checks/after/index.js +1 -6
  47. package/dist/checks/after/tools.js +1 -1
  48. package/dist/checks/tips/index.js +4 -2
  49. package/dist/commands/workflow/issues.js +25 -46
  50. package/dist/commands/workflow/repo.js +1 -0
  51. package/dist/commands/workflow/worktrees.js +74 -13
  52. package/dist/install/modules/core.js +81 -6
  53. package/dist/shared/settings.js +23 -10
  54. package/package.json +4 -2
  55. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  56. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
@@ -39,7 +39,6 @@ const base = (extra = {}) => ({
39
39
  STATIC_RESULT: "success",
40
40
  UNIT_RESULT: "success",
41
41
  UNIT_RAN: "12",
42
- UNIT_CACHE_SKIP: "",
43
42
  ...extra,
44
43
  });
45
44
 
@@ -51,10 +50,8 @@ const planned = (extra = {}) => ({
51
50
  STATIC_RESULT: "success",
52
51
  UNIT_RESULT: "success",
53
52
  UNIT_RAN: "12",
54
- UNIT_CACHE_SKIP: "false",
55
53
  INTEGRATION_RESULT: "success",
56
54
  INTEGRATION_RAN: "4",
57
- INTEGRATION_CACHE_SKIP: "false",
58
55
  ...extra,
59
56
  });
60
57
 
@@ -64,10 +61,8 @@ const skipPlan = (extra = {}) =>
64
61
  STATIC_RESULT: "skipped",
65
62
  UNIT_RESULT: "skipped",
66
63
  UNIT_RAN: "",
67
- UNIT_CACHE_SKIP: "",
68
64
  INTEGRATION_RESULT: "skipped",
69
65
  INTEGRATION_RAN: "",
70
- INTEGRATION_CACHE_SKIP: "",
71
66
  ...extra,
72
67
  });
73
68
 
@@ -215,19 +210,9 @@ test("an unparseable plan never lets a skipped lane pass as 'nothing planned'",
215
210
 
216
211
  // ── the exemptions ──────────────────────────────────────────────────────────
217
212
 
218
- test("cache_skip=true asserts no count", () => {
219
- greens(base({ UNIT_CACHE_SKIP: "true", UNIT_RAN: "" }));
220
- greens(base({ UNIT_CACHE_SKIP: "true", UNIT_RAN: "0" }));
221
- greens(planned({ INTEGRATION_CACHE_SKIP: "true", INTEGRATION_RAN: "0" }));
222
- });
223
-
224
- test("cache_skip=true does not excuse a failed lane", () => {
225
- reds(base({ UNIT_RESULT: "failure", UNIT_CACHE_SKIP: "true" }), "result=failure");
226
- });
227
-
228
- test("only the exact string 'true' is a cache skip", () => {
229
- reds(base({ UNIT_CACHE_SKIP: "yes", UNIT_RAN: "0" }), "0 tests");
230
- reds(base({ UNIT_CACHE_SKIP: "TRUE", UNIT_RAN: "0" }), "0 tests");
213
+ test("a <LANE>_CACHE_SKIP variable excuses no count", () => {
214
+ reds(base({ UNIT_CACHE_SKIP: "true", UNIT_RAN: "0" }), "0 tests");
215
+ reds(planned({ INTEGRATION_CACHE_SKIP: "true", INTEGRATION_RAN: "0" }), "0 tests");
231
216
  });
232
217
 
233
218
  test("EMPTY_COUNT=warn turns an unreported count into a warning, not a failure", () => {
@@ -262,12 +247,8 @@ test("a hyphenated lane reads <LANE>_ variables with underscores", () => {
262
247
  LANES: "e2e-web",
263
248
  E2E_WEB_RESULT: "success",
264
249
  E2E_WEB_RAN: "3",
265
- E2E_WEB_CACHE_SKIP: "",
266
250
  });
267
- reds(
268
- { LANES: "e2e-web", E2E_WEB_RESULT: "success", E2E_WEB_RAN: "0", E2E_WEB_CACHE_SKIP: "" },
269
- "bkit-tests-e2e-web",
270
- );
251
+ reds({ LANES: "e2e-web", E2E_WEB_RESULT: "success", E2E_WEB_RAN: "0" }, "bkit-tests-e2e-web");
271
252
  });
272
253
 
273
254
  test("lane names tolerate spaces around the commas", () => {
@@ -12,10 +12,19 @@
12
12
  * is not an ancestor of HEAD (a force-push rewrote the branch), the base falls back to
13
13
  * `event.before`.
14
14
  *
15
+ * Local mode gives the pre-push hook the same base, so a local slop scan compares against the
16
+ * commit CI's does: the repo comes from `git remote get-url origin`, `origin/<branch>` stands
17
+ * in for `event.before`, and ancestry is tested against the pushed commit (`--head`), which is
18
+ * not always the checked-out one. gh uses its own login.
19
+ *
15
20
  * Usage: node scripts/ci/lanes/resolve-push-base.mjs
16
21
  * (env: GH_TOKEN, REPO, BRANCH, BEFORE_SHA, WORKFLOW_FILE; optional SOURCE_FILE)
17
- * Output: the base SHA on stdout; the chosen source (`last-green-run`, `event-before`, ...) on
18
- * stderr, and in SOURCE_FILE when that env var names a file. Exit 0 always — every
22
+ * node scripts/ci/lanes/resolve-push-base.mjs --local --branch=dev --head=<pushed sha>
23
+ * (env: optional WORKFLOW_FILE, SOURCE_FILE)
24
+ * Output: the base SHA on stdout; the chosen source (`last-green-run`, `event-before`, ...;
25
+ * `origin/<branch>` in place of `event-before` in local mode) on stderr, and in
26
+ * SOURCE_FILE when that env var names a file. A source ending `(run lookup failed)` or
27
+ * `(resolver failed)` means the run list could not be read. Exit 0 always — every
19
28
  * failure (gh, git, unparseable output) falls back to `event.before`, itself a valid base.
20
29
  */
21
30
 
@@ -26,15 +35,42 @@ import { pathToFileURL } from "node:url";
26
35
  /** The workflow whose runs establish the base. Set WORKFLOW_FILE if your CI file has another name. */
27
36
  export const WORKFLOW_FILE = process.env.WORKFLOW_FILE || "bkit-ci.yml";
28
37
 
29
- /** Pure decision. `isAncestor(sha)` answers whether `sha` is an ancestor of HEAD. */
30
- export function choosePushBase({ lastGreenSha, beforeSha, isAncestor }) {
38
+ /**
39
+ * Pure decision. `isAncestor(sha)` answers whether `sha` is an ancestor of the pushed commit.
40
+ * `fallback` names the before-sha in the source (`event-before`, or `origin/<branch>` locally);
41
+ * `lookupFailed` marks a run list that could not be read.
42
+ */
43
+ export function choosePushBase({
44
+ lastGreenSha,
45
+ beforeSha,
46
+ isAncestor,
47
+ fallback = "event-before",
48
+ lookupFailed = false,
49
+ }) {
31
50
  if (lastGreenSha && isAncestor(lastGreenSha)) {
32
51
  return { base: lastGreenSha, source: "last-green-run" };
33
52
  }
34
- return {
35
- base: beforeSha ?? "",
36
- source: lastGreenSha ? "event-before (last green run is not an ancestor)" : "event-before",
37
- };
53
+ let source = fallback;
54
+ if (lookupFailed) source = `${fallback} (run lookup failed)`;
55
+ else if (lastGreenSha) source = `${fallback} (last green run is not an ancestor)`;
56
+ return { base: beforeSha ?? "", source };
57
+ }
58
+
59
+ /** `owner/repo` from a GitHub remote URL (https, ssh, scp-style), or "" when it has no such path. */
60
+ export function repoFromRemoteUrl(url) {
61
+ const match = /[/:]([^/:\s]+)\/([^/\s]+?)(?:\.git)?\/?$/.exec(String(url ?? "").trim());
62
+ return match ? `${match[1]}/${match[2]}` : "";
63
+ }
64
+
65
+ /** `--local`, `--branch=`, `--head=` from argv; anything else is ignored. */
66
+ export function parseArgs(argv) {
67
+ const args = { local: false, branch: "", head: "" };
68
+ for (const arg of argv) {
69
+ if (arg === "--local") args.local = true;
70
+ else if (arg.startsWith("--branch=")) args.branch = arg.slice("--branch=".length);
71
+ else if (arg.startsWith("--head=")) args.head = arg.slice("--head=".length);
72
+ }
73
+ return args;
38
74
  }
39
75
 
40
76
  /** How far back the run lookup reaches. A green run older than this falls back to event.before. */
@@ -53,7 +89,8 @@ export function newestRunSha(runs) {
53
89
  return newest ? newest.head_sha : "";
54
90
  }
55
91
 
56
- function lastGreenPushSha(repo, branch, now = new Date()) {
92
+ /** `{ sha, failed }`: the newest green push run's head, and whether the run list was unreadable. */
93
+ function lastGreenPushSha(repo, branch, fallbackName, now = new Date()) {
57
94
  const since = new Date(now.getTime() - LOOKBACK_DAYS * 86_400_000).toISOString().slice(0, 10);
58
95
  const path =
59
96
  `repos/${repo}/actions/workflows/${WORKFLOW_FILE}/runs` +
@@ -69,17 +106,17 @@ function lastGreenPushSha(repo, branch, now = new Date()) {
69
106
  if (error || status !== 0) {
70
107
  const reason = error ? error.message : String(stderr).split("\n")[0];
71
108
  console.error(
72
- `[resolve-push-base] could not list ${WORKFLOW_FILE} runs (${reason}) — using event.before`,
109
+ `[resolve-push-base] could not list ${WORKFLOW_FILE} runs (${reason}) — using ${fallbackName}`,
73
110
  );
74
- return "";
111
+ return { sha: "", failed: true };
75
112
  }
76
113
  // Unparseable output throws; main() catches it and falls back to event.before.
77
- return newestRunSha(JSON.parse(stdout || "[]"));
114
+ return { sha: newestRunSha(JSON.parse(stdout || "[]")), failed: false };
78
115
  }
79
116
 
80
- /** True only when `sha` is an ancestor of HEAD; any git failure is "not an ancestor" (logged). */
81
- function isAncestorOfHead(sha) {
82
- const { status, error } = spawnSync("git", ["merge-base", "--is-ancestor", sha, "HEAD"], {
117
+ /** True only when `sha` is an ancestor of `head`; any git failure is "not an ancestor" (logged). */
118
+ function isAncestorOf(sha, head, fallbackName) {
119
+ const { status, error } = spawnSync("git", ["merge-base", "--is-ancestor", sha, head], {
83
120
  stdio: "ignore",
84
121
  });
85
122
  // 0 = ancestor. 1 = not an ancestor. 128 = the SHA is not in this clone (a force-push dropped
@@ -88,22 +125,64 @@ function isAncestorOfHead(sha) {
88
125
  if (!error && (status === 1 || status === 128)) return false;
89
126
  const reason = error ? error.message : `git exited ${status}`;
90
127
  console.error(
91
- `[resolve-push-base] cannot test ancestry of ${sha} (${reason}) — using event.before`,
128
+ `[resolve-push-base] cannot test ancestry of ${sha} (${reason}) — using ${fallbackName}`,
92
129
  );
93
130
  return false;
94
131
  }
95
132
 
96
- export function main(env) {
133
+ /** stdout of a git command, or "" when it fails. */
134
+ function gitOut(args) {
135
+ const { status, stdout, error } = spawnSync("git", args, {
136
+ encoding: "utf8",
137
+ stdio: ["ignore", "pipe", "ignore"],
138
+ });
139
+ return !error && status === 0 ? stdout.trim() : "";
140
+ }
141
+
142
+ /**
143
+ * The resolver's inputs. CI: env vars, ancestry against HEAD. Local (`--local`): repo from
144
+ * origin's URL, before-sha from `origin/<branch>`, ancestry against `--head`.
145
+ */
146
+ export function resolveInputs(env, argv) {
147
+ const args = parseArgs(argv);
148
+ if (!args.local) {
149
+ return {
150
+ repo: env.REPO,
151
+ branch: env.BRANCH,
152
+ beforeSha: env.BEFORE_SHA,
153
+ head: "HEAD",
154
+ fallback: "event-before",
155
+ fallbackName: "event.before",
156
+ };
157
+ }
158
+ const branch = args.branch || "dev";
159
+ return {
160
+ repo: repoFromRemoteUrl(gitOut(["remote", "get-url", "origin"])),
161
+ branch,
162
+ beforeSha: gitOut(["rev-parse", "--verify", "--quiet", `origin/${branch}^{commit}`]),
163
+ head: args.head || "HEAD",
164
+ fallback: `origin/${branch}`,
165
+ fallbackName: `origin/${branch}`,
166
+ };
167
+ }
168
+
169
+ export function main(env, argv = []) {
170
+ const input = resolveInputs(env, argv);
97
171
  let result;
98
172
  try {
173
+ const lastGreen = lastGreenPushSha(input.repo, input.branch, input.fallbackName);
99
174
  result = choosePushBase({
100
- lastGreenSha: lastGreenPushSha(env.REPO, env.BRANCH),
101
- beforeSha: env.BEFORE_SHA,
102
- isAncestor: isAncestorOfHead,
175
+ lastGreenSha: lastGreen.sha,
176
+ beforeSha: input.beforeSha,
177
+ isAncestor: (sha) => isAncestorOf(sha, input.head, input.fallbackName),
178
+ fallback: input.fallback,
179
+ lookupFailed: lastGreen.failed,
103
180
  });
104
181
  } catch (err) {
105
- console.error(`[resolve-push-base] unexpected failure (${err.message}) — using event.before`);
106
- result = { base: env.BEFORE_SHA ?? "", source: "event-before (resolver failed)" };
182
+ console.error(
183
+ `[resolve-push-base] unexpected failure (${err.message}) — using ${input.fallbackName}`,
184
+ );
185
+ result = { base: input.beforeSha ?? "", source: `${input.fallback} (resolver failed)` };
107
186
  }
108
187
  const { base, source } = result;
109
188
  console.error(`[resolve-push-base] base=${base || "(none)"} source=${source}`);
@@ -116,4 +195,6 @@ export function main(env) {
116
195
  }
117
196
  }
118
197
 
119
- if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main(process.env);
198
+ if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
199
+ main(process.env, process.argv.slice(2));
200
+ }
@@ -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
@@ -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,6 +6,36 @@ Format: `## [version] — YYYY-MM-DD`
6
6
 
7
7
  ---
8
8
 
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
+
9
39
  ## [5.5.0] — 2026-10-21
10
40
 
11
41
  ### Breaking Changes
package/README.md CHANGED
@@ -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
@@ -73,7 +73,6 @@ export function detectCiYmlMissingActionlint(cwd) {
73
73
  detect: ".github/workflows/bkit-ci.yml (adopted from bkit's template) has no actionlint step. yaml.safe_load accepts workflows that are valid YAML but invalid GitHub Actions (e.g. doubled quotes inside ${{ }}, an always-true `if:` block scalar); actionlint is GHA-aware and catches them.",
74
74
  action: "Add an actionlint step among the static checks in .github/workflows/bkit-ci.yml (before the test/build group):\n\n" +
75
75
  " - name: Run actionlint\n" +
76
- " if: steps.cache.outputs.skip != 'true'\n" +
77
76
  " run: |\n" +
78
77
  ' curl -sSfL https://raw.githubusercontent.com/rhysd/actionlint/v1.7.12/scripts/download-actionlint.bash -o "$RUNNER_TEMP/download-actionlint.bash"\n' +
79
78
  ' bash "$RUNNER_TEMP/download-actionlint.bash" 1.7.12 "$RUNNER_TEMP"\n' +