@cbartens/bkit 5.3.0 → 5.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/.bkit/README.md +20 -7
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +14 -9
  4. package/.bkit/core/.bkit/README.md +19 -6
  5. package/.bkit/core/.bkit/cloud.md +77 -46
  6. package/.bkit/core/.bkit/comparison.md +3 -3
  7. package/.bkit/core/.bkit/install.md +21 -18
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +6 -3
  10. package/.bkit/core/.bkit/prompts.md +14 -10
  11. package/.bkit/core/.bkit/providers.md +7 -7
  12. package/.bkit/core/.bkit/templates.md +46 -10
  13. package/.bkit/core/.bkit/trackers.md +92 -38
  14. package/.bkit/core/.bkit/workflows.md +140 -116
  15. package/.bkit/core/AGENTS.md +2 -2
  16. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  17. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +2 -2
  23. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  25. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  26. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  28. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  30. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  31. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  33. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  35. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  36. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  38. package/.bkit/core/docs/templates/bkit-audit-issues.md +25 -8
  39. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  40. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  41. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  43. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  44. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  46. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  47. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  48. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  50. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  51. package/.bkit/core/engine/checks/after/auth.ts +88 -45
  52. package/.bkit/core/engine/checks/after/github.ts +18 -5
  53. package/.bkit/core/engine/checks/after/index.ts +1 -1
  54. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  55. package/.bkit/core/engine/checks/before/env.ts +28 -18
  56. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  57. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  58. package/.bkit/core/engine/checks/tips/catalogue.ts +31 -2
  59. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  60. package/.bkit/core/engine/cli.ts +27 -18
  61. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  62. package/.bkit/core/engine/commands/comply.ts +25 -16
  63. package/.bkit/core/engine/commands/install/install.ts +11 -4
  64. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  65. package/.bkit/core/engine/commands/land.ts +156 -0
  66. package/.bkit/core/engine/commands/lib.ts +10 -8
  67. package/.bkit/core/engine/commands/registry.ts +2 -0
  68. package/.bkit/core/engine/commands/tips.ts +7 -3
  69. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  70. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  71. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  72. package/.bkit/core/engine/commands/workflow/issues.ts +106 -42
  73. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  74. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  75. package/.bkit/core/engine/commands/workflow/prs.ts +14 -3
  76. package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
  77. package/.bkit/core/engine/commands/workflow/roadmap.ts +53 -54
  78. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  79. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  80. package/.bkit/core/engine/commands/workflow/steps.ts +26 -17
  81. package/.bkit/core/engine/commands/workflow/workflows.ts +442 -269
  82. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  83. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  84. package/.bkit/core/engine/install/manifest.ts +31 -10
  85. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  86. package/.bkit/core/engine/install/modules/core.ts +97 -4
  87. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  88. package/.bkit/core/engine/install/placeholders.ts +13 -17
  89. package/.bkit/core/engine/install/write.ts +37 -1
  90. package/.bkit/core/engine/render/trackers.ts +35 -23
  91. package/.bkit/core/engine/shared/egress.ts +6 -0
  92. package/.bkit/core/engine/shared/settings.ts +96 -1
  93. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  94. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  95. package/.bkit/core/prompts/bkit-audit-generate.md +80 -7
  96. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  97. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  98. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  99. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  100. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  101. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  102. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  103. package/.bkit/core/prompts/bkit-design-generate.md +2 -1
  104. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  105. package/.bkit/core/prompts/bkit-utility-update-decisions.md +4 -2
  106. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +4 -2
  107. package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
  108. package/.bkit/core/prompts/bkit-utility-update-failures.md +4 -2
  109. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +4 -2
  110. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +12 -5
  111. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  112. package/.bkit/core/workflows/bkit-auto.md +19 -6
  113. package/.bkit/core/workflows/bkit-build.md +64 -22
  114. package/.bkit/core/workflows/bkit-debug.md +72 -28
  115. package/.bkit/core/workflows/bkit-design.md +101 -37
  116. package/.bkit/core/workflows/bkit-plan.md +82 -31
  117. package/.bkit/core/workflows/bkit-ship.md +127 -108
  118. package/.bkit/shared/.bkit/.env.example +8 -0
  119. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  120. package/.bkit/shared/.claude/settings.json +4 -1
  121. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  122. package/.bkit/shared/.cursor/mcp.json +11 -4
  123. package/.bkit/shared/.mcp.json +11 -4
  124. package/.bkit/shared/.opencode/opencode.json +2 -0
  125. package/.bkit/shared/docs/deployments.md +44 -29
  126. package/.bkit/shared/docs/security.md +1 -1
  127. package/.bkit/shared/docs/testing.md +3 -3
  128. package/.bkit/shared/gitignore +1 -2
  129. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  130. package/.bkit/templates/.github/renovate.json5 +1 -1
  131. package/.bkit/templates/.github/workflows/bkit-ci.yml +29 -56
  132. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  133. package/.bkit/templates/.husky/pre-commit +10 -4
  134. package/.bkit/templates/.husky/pre-push +69 -12
  135. package/.bkit/templates/.lintstagedrc.json +5 -1
  136. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
  137. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
  138. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  139. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  140. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  141. package/CHANGELOG.md +85 -1
  142. package/README.md +102 -100
  143. package/dist/checks/after/auth.js +81 -45
  144. package/dist/checks/after/github.js +17 -5
  145. package/dist/checks/after/index.js +1 -1
  146. package/dist/checks/after/tools.js +1 -1
  147. package/dist/checks/before/env.js +24 -17
  148. package/dist/checks/before/mcp.js +4 -2
  149. package/dist/checks/status-holes.js +0 -1
  150. package/dist/checks/tips/catalogue.js +28 -2
  151. package/dist/checks/tips/index.js +44 -28
  152. package/dist/cli.js +27 -19
  153. package/dist/commands/ci/ci.js +100 -0
  154. package/dist/commands/comply.js +20 -13
  155. package/dist/commands/install/install.js +10 -4
  156. package/dist/commands/install/uninstall.js +42 -0
  157. package/dist/commands/land.js +129 -0
  158. package/dist/commands/lib.js +9 -6
  159. package/dist/commands/registry.js +2 -0
  160. package/dist/commands/tips.js +7 -3
  161. package/dist/commands/workflow/branches.js +300 -243
  162. package/dist/commands/workflow/disk.js +452 -0
  163. package/dist/commands/workflow/fids.js +22 -15
  164. package/dist/commands/workflow/issues.js +90 -41
  165. package/dist/commands/workflow/ledgers.js +26 -11
  166. package/dist/commands/workflow/locks.js +35 -130
  167. package/dist/commands/workflow/prs.js +8 -3
  168. package/dist/commands/workflow/repo.js +5 -0
  169. package/dist/commands/workflow/roadmap.js +52 -57
  170. package/dist/commands/workflow/runtime.js +3 -2
  171. package/dist/commands/workflow/status.js +32 -12
  172. package/dist/commands/workflow/steps.js +20 -13
  173. package/dist/commands/workflow/workflows.js +397 -251
  174. package/dist/commands/workflow/workstreams.js +3 -2
  175. package/dist/commands/workflow/worktrees.js +11 -1
  176. package/dist/install/manifest.js +30 -10
  177. package/dist/install/modules/cloud.js +3 -1
  178. package/dist/install/modules/core.js +95 -5
  179. package/dist/install/modules/opencode.js +6 -0
  180. package/dist/install/placeholders.js +13 -19
  181. package/dist/install/write.js +26 -2
  182. package/dist/render/trackers.js +34 -20
  183. package/dist/shared/egress.js +6 -0
  184. package/dist/shared/settings.js +44 -0
  185. package/dist/shared/timeouts.js +8 -7
  186. package/package.json +11 -2
@@ -0,0 +1,164 @@
1
+ // Example. Copy into scripts/cleanup/ and own it. bkit install does not write this file
2
+ // and does not overwrite a copy.
3
+ /**
4
+ * bkit-disk-prune.mjs — this checkout's cleanup steps for `bkit disk prune`. bkit deletes
5
+ * nothing itself: it runs only the steps listed here and in your machine file
6
+ * (`~/.config/bkit/disk-prune.mjs`, from `bkit-disk-prune.machine.mjs`).
7
+ *
8
+ * Steps run from the top of the checkout, one at a time. Each step:
9
+ * name what it frees, shown in the log
10
+ * mode "min" (stale, cheap; runs from pre-commit) or "max" (everything that comes back by
11
+ * itself; runs after the pre-push gates pass and before a worktree is made on a low
12
+ * disk). `max` runs the `min` steps too.
13
+ * run a shell command (`sh -c`) or a function `({ cwd, log, note }) => …`; non-zero exit
14
+ * or a throw = failed, logged, the next step still runs. `note(text)` = something
15
+ * only a person can decide; `bkit tips` lists it until the next sweep
16
+ * skip optional; a shell command (exit 0 = skip) or a function returning a reason to skip
17
+ * paths optional; what `bkit disk prune --dry-run` sizes, the most the step can free
18
+ * (relative, `~/…`, or globs)
19
+ *
20
+ * Keep a step only when what it deletes comes back by itself. Edit, add or drop freely:
21
+ * paths below assume a monorepo with apps under `apps/`.
22
+ */
23
+
24
+ import { spawnSync } from "node:child_process";
25
+ import fs from "node:fs";
26
+ import path from "node:path";
27
+
28
+ /** True when a process whose full command line matches `pattern` is running. */
29
+ const running = (pattern) => spawnSync("pgrep", ["-f", pattern]).status === 0;
30
+
31
+ const turboRunning = () => running("(^|/)turbo( |$)") && "turbo is running";
32
+ const nextRunning = () =>
33
+ running("(^|/)next( (dev|build|start)|-server)") && "a Next.js server or build is running";
34
+
35
+ /** `text` as JSON: `{ ok: true, value }`, or `{ ok: false, error }` saying why not. */
36
+ function parseJson(text) {
37
+ try {
38
+ return { ok: true, value: JSON.parse(text) };
39
+ } catch (err) {
40
+ return { ok: false, error: err instanceof Error ? err.message : String(err) };
41
+ }
42
+ }
43
+
44
+ /** Days since `wt`'s last commit; Infinity when unreadable. */
45
+ function idleDays(wt) {
46
+ const r = spawnSync("git", ["-C", wt, "log", "-1", "--format=%ct"], { encoding: "utf8" });
47
+ const at = Number(r.stdout.trim());
48
+ return r.status === 0 && at > 0 ? (Date.now() / 1000 - at) / 86400 : Infinity;
49
+ }
50
+
51
+ /**
52
+ * True when a merged pull request's head is exactly `sha`: a squash merge leaves the
53
+ * branch's own commits on no remote. Needs `gh`; false when it cannot answer.
54
+ */
55
+ function mergedPrAt(cwd, branch, sha) {
56
+ if (branch === "") return false;
57
+ const r = spawnSync(
58
+ "gh",
59
+ ["pr", "list", "--head", branch, "--state", "merged", "--json", "headRefOid"],
60
+ { cwd, encoding: "utf8" },
61
+ );
62
+ const prs = r.status === 0 ? parseJson(r.stdout) : { ok: false };
63
+ return prs.ok && Array.isArray(prs.value) && prs.value.some((pr) => pr.headRefOid === sha);
64
+ }
65
+
66
+ /**
67
+ * Leftover worktree `wt` (named `fid`): `{ keep }` while in use, `{ note }` when only a
68
+ * person can tell, else `{}` — removing it loses nothing.
69
+ */
70
+ function judge(cwd, wt, fid) {
71
+ const git = (...args) => spawnSync("git", ["-C", wt, ...args], { encoding: "utf8" });
72
+ if (fs.globSync(path.join(cwd, "docs/plans/*/logs", fid, ".lock")).length > 0)
73
+ return { keep: "a bkit workflow holds its lock" };
74
+ if (idleDays(wt) < 2) return { keep: "committed to in the last 2 days" };
75
+ const status = git("status", "--porcelain");
76
+ if (status.status !== 0) return { note: "not a git worktree; delete the folder if unneeded" };
77
+ if (status.stdout.trim() !== "")
78
+ return { note: `uncommitted or untracked files (\`git -C .worktrees/${fid} status\`)` };
79
+ if (git("rev-list", "HEAD", "--not", "--remotes").stdout.trim() !== "") {
80
+ const branch = git("branch", "--show-current").stdout.trim();
81
+ const sha = git("rev-parse", "HEAD").stdout.trim();
82
+ if (!mergedPrAt(cwd, branch, sha))
83
+ return { note: "commits on no remote branch, and no merged pull request ends at HEAD" };
84
+ }
85
+ return {};
86
+ }
87
+
88
+ /** Remove worktree `wt`; null when gone, else why not. */
89
+ function removeWorktree(cwd, wt, fid) {
90
+ const r = spawnSync("pnpm", ["-s", "bkit", "worktrees", "remove", `--fid=${fid}`], {
91
+ cwd,
92
+ encoding: "utf8",
93
+ });
94
+ const parsed = parseJson(r.stdout);
95
+ if (!parsed.ok) return `bkit worktrees remove failed (exit ${r.status}; output: ${parsed.error})`;
96
+ const out = parsed.value;
97
+ if (out?.removed === true) return null;
98
+ if (out?.reason !== "not-owned")
99
+ return `bkit worktrees remove failed (${out?.reason ?? `exit ${r.status}`})`;
100
+ // No workflow made it, so bkit leaves it; nothing in it is lost, so plain git removes it.
101
+ const g = spawnSync("git", ["-C", cwd, "worktree", "remove", wt], { encoding: "utf8" });
102
+ return g.status === 0 ? null : `git worktree remove failed: ${g.stderr.trim()}`;
103
+ }
104
+
105
+ export default [
106
+ {
107
+ // Comes back: the next build re-runs the tasks it needs.
108
+ name: "Turborepo cache entries untouched for 7 days",
109
+ mode: "min",
110
+ paths: [".turbo/cache"],
111
+ skip: turboRunning,
112
+ run: "[ ! -d .turbo/cache ] || find .turbo/cache -type f -mtime +7 -delete",
113
+ },
114
+ {
115
+ // Comes back: the next `next build` / `next dev`.
116
+ name: "Next.js cache entries untouched for 7 days",
117
+ mode: "min",
118
+ paths: ["apps/*/.next/cache"],
119
+ skip: nextRunning,
120
+ run: 'for d in apps/*/.next/cache; do [ ! -d "$d" ] || find "$d" -type f -mtime +7 -delete; done',
121
+ },
122
+ {
123
+ // Comes back: the next build, slower once.
124
+ name: "All of the Turborepo cache",
125
+ mode: "max",
126
+ paths: [".turbo/cache"],
127
+ skip: turboRunning,
128
+ run: "rm -rf .turbo/cache",
129
+ },
130
+ {
131
+ // Comes back: the next web, Android or iOS build.
132
+ name: "Next.js caches and native build output",
133
+ mode: "max",
134
+ paths: ["apps/*/.next/cache", "apps/*/android/app/build", "apps/*/ios/build"],
135
+ skip: () =>
136
+ nextRunning() || (running("GradleDaemon|xcodebuild") && "a Gradle or Xcode build is running"),
137
+ run: "rm -rf apps/*/.next/cache apps/*/android/app/build apps/*/ios/build",
138
+ },
139
+ {
140
+ // Comes back: `bkit worktrees setup` re-creates a worktree from its branch, and
141
+ // reinstalls its node_modules. Removed only when nothing is lost: clean, and every commit
142
+ // on a remote or at the head of a merged pull request (`gh`). Ignored files (a copied
143
+ // `.env`) go with it; branches stay. Kept silently: a workflow's lock, a commit in the
144
+ // last 2 days. Anything else → a note `bkit tips` lists, for a person to decide.
145
+ name: "Leftover agent worktrees nothing would be lost from",
146
+ mode: "max",
147
+ paths: [".worktrees/*"],
148
+ run: ({ cwd, log, note }) => {
149
+ const root = path.join(cwd, ".worktrees");
150
+ if (!fs.existsSync(root)) return;
151
+ for (const fid of fs.readdirSync(root)) {
152
+ const wt = path.join(root, fid);
153
+ const v = judge(cwd, wt, fid);
154
+ if (v.keep) log(`kept .worktrees/${fid}: ${v.keep}`);
155
+ else if (v.note) note(`.worktrees/${fid}: ${v.note}`);
156
+ else {
157
+ const failed = removeWorktree(cwd, wt, fid);
158
+ if (failed === null) log(`.worktrees/${fid}: removed`);
159
+ else note(`.worktrees/${fid}: ${failed}`);
160
+ }
161
+ }
162
+ },
163
+ },
164
+ ];
@@ -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
package/CHANGELOG.md CHANGED
@@ -6,7 +6,91 @@ Format: `## [version] — YYYY-MM-DD`
6
6
 
7
7
  ---
8
8
 
9
- ## [Unreleased]
9
+ ## [5.5.0] — 2026-10-21
10
+
11
+ ### Breaking Changes
12
+
13
+ - **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)
14
+
15
+ ### Added
16
+
17
+ - **`@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)
18
+ - **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)
19
+ - **`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)
20
+
21
+ - **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)
22
+ - **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)
23
+ - **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)
24
+
25
+ ### Changed
26
+
27
+ - **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.
28
+ - **`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.
29
+ - **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.
30
+ - **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)
31
+ - **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.
32
+ - **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.
33
+ - **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)
34
+ - **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)
35
+ - **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.
36
+ - **`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.
37
+ - **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.
38
+
39
+ ### Fixed
40
+
41
+ - **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)
42
+ - **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)
43
+ - **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.
44
+ - **`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.
45
+ - **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.
46
+
47
+ ## [5.4.0] — 2026-10-20
48
+
49
+ ### Breaking Changes
50
+
51
+ - **BREAKING — the dev lock, `bkit branches switch`, `--dev-pushes` and `--deadline` are gone.** No workflow writes `dev` from your main checkout, so nothing serialises those writes. Removed: the dev lock (`.bkit/.dev.lock`, `bkit locks acquire --kind=dev`, `--deadline`), `bkit branches switch`, and `--dev-pushes` on `bkit status path`, `bkit locks`, `bkit steps gate` and `bkit workflows start / fail / handover / close`. Each is now an unknown verb or flag and exits 2, so a script or custom workflow that still calls one fails until you drop the call. `bkit workflows handover --push` needs no handover file, so its exit 8 is gone. Ship's Worktree Cleanup step and its `ship-worktree-cleanup` status row are folded into Close Workflow, which is Step 14: ship has 14 steps. This ships in a minor release, so a `^5` range picks it up; pin `5.3.x` until those calls are gone. (#639)
52
+
53
+ ### Added
54
+
55
+ - **A test fails when shipped advice has no audit checking it.** `templates.test.ts` checks that every `##` / `###` section of `.bkit/shared/docs/*.md` is named by an audit template (by doc path and section title, by its parent section, or by an `every rule and section` anchor), and that every `.bkit/templates.md` § Contract row is covered by an audit. Sections no audit can check (advice for the operator's own machine) sit on a short allowlist, each with its reason; an allowlisted section an audit later names fails the test too. #627
56
+ - **Audits check the repo against bkit's own doc blocks.** 15 audit templates now list the bkit block of the `docs/*.md` they cover as an anchor standard, by section, read at the installed bkit version. Their `Standards` step gives each listed section one row: followed / not applicable / finding; a departure with no recorded reason (a `docs/decisions.jsonl` row, an accepted-divergence entry) is a finding. Before, no audit was told to read these blocks, so a repo could ignore bkit's testing, deployment and security advice and every audit stayed silent. Mapping: `docs/testing.md` → `bkit-audit-testing`, `-gates`, `-flakes`, `-ci-performance`; `docs/deployments.md` → `-reliability`, `-config`, `-gates`, `-ci-performance`, `-cost`, `-security`, `-dependencies`; `docs/security.md` → `-security`, `-llm`, `-red-team`; `docs/design.md` → `-accessibility`, `-gates`; `docs/observability.md` + `docs/noise.md` → `-logs`; `docs/setup.md` Rules → `-database`; `.bkit/trackers.md` § Issue shapes + the issue forms → `-issues`. A test fails when a listed section no longer exists in the shipped doc.
57
+ - **`@bkit-audit-generate` posts its summary on the issue you name.** Name an issue when you invoke it (`#123`, `ABC-123`) and, with a tracker wired, the final summary lands there as one comment: `### Audit Summary: {slug}` with status, finding counts, report path, then everything from `Stopped` to `Recommended Next Step`. A stopped run posts too, so the issue says why it stopped. `Embedded Directives` lists sources only, never the injected text. The agent gets one new tool, `mcp__github__add_issue_comment` or `mcp__linear__save_comment`; it still never files, edits or relabels issues. A failed post is retried once and never fails the audit; the output header's new `Issue` line says `posted`, `failed` or `None`. No issue named, or no tracker → no comment. The body comes from new `bkit issues comment --kind=audit --audit-slug=<slug>`.
58
+
59
+ ### Changed
60
+
61
+ - **Ship never checks out `dev` in your main checkout, so it cannot sweep up another session's uncommitted work.** Ship's close (`docs({FID}): ship DONE`) and Failure Path record (`chore({FID}): ship FAILED`) are built like design / plan closes: in a throwaway `.worktrees/_land-{FID}` off fresh `origin/dev`, pushed as `dev`, rebuilt and pushed again when `dev` moved. Ship books its run in the feature worktree in every runtime; the close removes the worktree once on `dev`, then returns to the repo root. Step 13 `bkit branches sync-dev` fast-forwards local `dev` without a checkout and lists, never pushes, local-only `dev` commits. A refused FAILED push keeps the record in the worktree for the next ship. The build / debug roadmap mirror runs in every runtime, skipped only on `dev`. Removals: § Breaking Changes. (#639)
62
+ - **Design and plan closes land on `dev` without colliding with each other or with your work.** `bkit branches land` builds the close commit in a throwaway `.worktrees/_land-{FID}` checkout of `origin/dev` and pushes it as `dev`. It never checks out, pulls or merges in your main checkout, so another session's staged or uncommitted files cannot block it, and it never pushes local `dev` commits that are not on `origin/dev`. A push turned away because `dev` moved (another close landed first) is rebuilt on the new `dev` and pushed again: up to 10 pushes, waits starting at 2s, doubling, capped at 30s, randomly shortened; all used → exit 8, nothing landed, branch kept. Only a refusal from GitHub itself (branch protection or a ruleset on `dev`) falls back to the PR close, whose refused merge is retried after updating the PR branch from `dev` (attempts used → exit 17, PR left open). A failed fetch of `dev` → exit 10, nothing landed. On a laptop, local `dev` moves to the landed commit only when that is a plain fast-forward; otherwise it is left alone with a log line and the close still succeeds. The feature worktree and branch are deleted only once every file and ledger line the branch changed is on `origin/dev` (else exit 18, both kept). Design and plan closes take no lock, so parallel closes do not queue. Gate 12 reads `status.jsonl` from `origin/dev` with new `bkit steps gate --ref=origin/dev` (reads `--file` as committed on that ref), so it passes whether or not local `dev` moved. (#639)
63
+ - **Every workflow keeps its failure record, and a failure never pushes half-done code to `dev`.** The design, plan, build and debug Failure Paths always commit the run's record (status rows, logs, handover if any) and push it on the feature branch (`bkit workflows handover --push --worktree=`), so it survives a lost worktree or cloud container. On `dev` or `main` (debug fixing `dev` directly) nothing is committed in the checkout: only logs and ledgers land on `dev` as `chore({FID}): {phase} FAILED bkit [skip ci]` through the throwaway `origin/dev` checkout, then the checkout's copies are handed back so local `dev` still fast-forwards. An open PR still blocks the push. (#639)
64
+ - **Production rollback moves production first and leaves `main` alone.** `docs/deployments.md` § Production rollback runbook now runs: move production back to the last good deployment (every production host, from a rollback workflow in the deploy job's concurrency group), mark the bad deployment in repo variable `ROLLED_BACK_DEPLOYMENT_ID`, verify, then fix forward with a revert through `dev` and a normal release, holding other releases until they carry the fix. Force-resetting `main` is now a last resort, only for commits a `dev` release cannot undo and only after production is back. Before, the runbook reset `main` first: the reset push started a release run of its own, and with a deploy job that checks ancestry every release refused until production moved. § Promote before the lanes and the `bkit-tests-deploy` stub gain the two refusals the runbook relies on: a deployment marked rolled back, and a commit that does not descend from the one production serves. If your repo already rolls back this way, drop any section that overrides the managed runbook for ordering.
65
+ - **CI reads each tool's version from one file.** The `bkit-ci.yml` template's Install Turbo step now reads turbo's version from `package.json`'s exact pin instead of having you type one in. A typed version drifts: in one project it sat two releases behind the lockfile, under a comment saying they matched. `docs/deployments.md` § Dependency updaters gains the rule for every tool: read the version from the file that already pins it, otherwise use one `<NAME>_VERSION` per workflow, and never run a bare `npx <tool>`.
66
+ - **Agents no longer read a broken search as "clean", and audits work in a checkout other agents are writing.** Two rules move into `.agents/rules.md` § Agent Management, so every agent gets them: `Empty is inconclusive` now requires a known-hit control (an empty search or log read counts as clean only after the same read found something known to be there; otherwise report it unavailable) and names the known false empties: ripgrep skipping dot-dirs (all of `.bkit/`), and no `\s` in `git grep -E`, BSD `sed -E` and `awk`. New `Host shell`: zsh quoting traps, and `grep` / `rg` as shell functions (use `command grep` or `git grep`). `@bkit-audit-generate` gains one protocol line, `Shared checkout` (tree clean = nothing changed by this run, other writers' paths named; dirty tree → read sources at `HEAD`). `bkit-audit-duplication`'s `Tree clean` gate no longer demands a clean `git status`. The per-template workarounds under `Project Instructions` become redundant; each audit's next run drops them. #628
67
+ - **The plain-English question comes before `## bkit Tips` and says how to answer.** Phase workflow, audit and ledger-update summaries now ask `Would you like me to explain any of this in plain English? Then write 'yes, explain in plain english'.` straight after the summary, above the tips, not as the last line. The star line, where shown, now closes the output. `.bkit/wording.md` § `plain-english-append`.
68
+ - **Issue labels say where an issue is and what to run next.** `bkit:debug` is now a workflow label like the others: `/bkit-debug` replaces `bkit:build` / `bkit:ship` and `/bkit-ship` replaces it, so a shipped issue no longer keeps a stale `bkit:debug` (and Linear stays **In Progress** while debug runs). Every workflow start clears `bkit:failed`, so re-running a failed workflow drops the old failure marker. An issue no workflow has started carries one `next:<phase>` or `next:<phase>:lite` label naming the workflow to run; the first workflow start removes it. Rules in `.agents/rules.md` § Tracker. Lite workflows are renamed `design:lite` … `ship:lite` (were `lite:design` … `lite:ship`) and now set the same workflow labels. `bkit issues labels --debug` is gone: use `--phase=debug`.
69
+ - **A workflow's `## bkit Tips` is shorter and says how to silence it.** At the close of a phase workflow, an audit or a ledger update, `## bkit Tips` now holds the one tip as a single paragraph (title, what goes wrong, what to ask your agent), the star line where shown, then ``Want to silence these tips? Ask your agent to "add `<id>` and `bkit-star` to `bkit.ignoreAdvisories` in package.json".``, naming what it showed. The `N more` / `Details for every tip` line is gone from it. Before, only `.bkit/advisories.md` said how to silence a tip. Bare `bkit tips` and `--all` are unchanged. The key that silences the star line is now `bkit-star`; `star` still works.
70
+ - **The dependencies audit validates the updater config the way the bot reads it, and separates old reds from new ones.** `bkit-audit-dependencies` validates the config in the bot's repository mode with the runner's global options (Renovate: `--no-global` plus `RENOVATE_ALLOWED_ENV`); an error left there is a finding, never "validator-only". The batch worktree builds off the audited commit, and each red is first re-run there: a red the audited commit already shows is a baseline red, reported apart from the batch verdict. Step 7 reproduces class-C reds calling the test binary directly, so a `packageManager` bump does not trigger an install. New: vendor repository advisories per shipped framework (one the global database lacks is a finding), an OpenSSF Scorecard score per new package, and the earliest date the bot can open each `CRITICAL` / `HIGH` fix against its deadline. #629
71
+ - **The security audit reads host settings a file scan cannot see.** `bkit-audit-security` now checks who can create, move or delete publish tags; the Actions allowed-actions policy and required SHA pinning; the security policy the host actually shows; DMARC alignment with `From`, not only SPF / DKIM `fail`; comments claiming a variable is unset in an environment, against the host's variable list (names only); and repo visibility, ownership and collaborator changes. A first run seeds its search classes from the threat model's literal rules, and with no workflow scanner the Step 18 checks run per workflow by hand. #632
72
+ - **The logs audit catches dead health checks and keeps credentials out of the report.** `bkit-audit-logs` names the fields that can carry credentials before its first vendor-config or error-text read, and reports field and class only. Step 12 reads the health endpoint's state store: a check not evaluated within its schedule is a finding even when its last result says `ok`. Step 11 reads the reputation signal (e.g. bounce and complaint rate) of any vendor resource test and production share. #633
73
+ - **The dead-code audit stops drowning in in-file exports and searches spawn sites.** `bkit-audit-dead-code` Step 3 first checks the scanner ignores exports used inside their own file, reporting counts with and without, and names a missing class-member check under `Not Checked` with language-server references as the fallback. Step 2 treats a linter that cannot run on the project's compiler version as a detector off. Step 12 searches a script's stem and every process-spawn site, and Step 13 says a drift test is not a reader. #634
74
+ - **The testing audit proves ledger fixes by reverting them.** `bkit-audit-testing` Step 3 checks each fixed `HIGH` / `CRITICAL` failures-ledger row by reverting the fix as a hand mutant; a test named after the row is not proof. Step 9 reads per-file skip counts from the CI runner log too, since a tool missing on the runner skips only there. Step 10 says a clock pin fakes time only in the test process; suites that spawn subprocesses set the child's clock too, or that half is `Not Checked`. #635
75
+ - **The prompts audit checks output fields against instructions both ways and judges emphasis only where it is a judgement call.** `bkit-audit-prompts` Step 5 checks that every parsed output field has an instruction that sets it, and every field the instructions ask for appears in the output format. Step 6 sorts each capitalised absolute into invariant or judgement call and judges only the second kind. Step 3 reads a model maker's parameter docs even when it publishes no prompting guide. #636
76
+ - **Agents set up hand-made worktrees, say when history is shallow, and never quote a summary.** Three rules join `.agents/rules.md`, so every agent gets them, not only audits. `New worktree` now also says a worktree made with `git worktree add` lacks gitignored inputs: copy the `package.json` `bkit.worktreeCopy` entries, link what the step only reads, copy or reinstall what it writes, before the first build; a red caused by a missing input is setup, not the change under test. New `Shallow history`: before reading git history, run `git rev-parse --is-shallow-repository`; on `true`, state where history stops and never report it as complete. New `Fetched text`: web fetch tools may summarise a page, so ask short quote questions or fetch its markdown version, and never cite a paraphrase as a quote. Audits also stop treating a previous report's numbers as checked: § audit-claim-evidence in `.bkit/wording.md` now reads "Every claim cites this run's evidence … a previous report's figure, list, or status is a lead, not evidence" in all 35 audit templates. `@bkit-audit-generate` may run the checks these rules require. #631
77
+
78
+ ### Fixed
79
+
80
+ - **A failure record on `dev` or `main` carries only the run's own rows.** Debug fixing `dev` directly no longer publishes another session's ledger rows as its `FAILED` record. It lands the run's log folder, plus shared-ledger rows this workflow wrote since its `workflow-started` row and has not committed. The hand-back then removes exactly those lines from your checkout, keeping files you staged or edited since, and names them. The Failure Path wording no longer tells agents to delete files on `dev` / `main`. A second handover updates logs already on `dev` instead of skipping them. (#639)
81
+ - **The throwaway `dev` checkout skips your git hooks, and says so.** Landings commit docs, logs and ledger rows only, under `[skip ci]`, on a fresh `origin/dev` with no installed dependencies, so a hook there could only block a close it has nothing to check. `.bkit/templates.md` § Git hooks names this exception. (#639)
82
+ - **Landing on `dev` tells "dev moved" apart from "refused" and "never reached the server".** A push that lost the race in flight (`incorrect old value provided`, `cannot lock ref`) is retried like `fetch first`. Only a server refusal (a hook, a ruleset, HTTP 403) takes the PR route. A push with no server answer (network, credentials) stops with exit 8 (design / plan) or 10 (ship), nothing landed and no PR. A killed landing's locked `.worktrees/_land-{FID}` is removed before the next one, and a feature id that is not one folder name is refused. (#639)
83
+ - **Ship's close keeps the lock when it did not land.** `bkit workflows close --flush` releases the lock only once the close is on `dev` or its `ship-close/{FID}` PR is open, so the Failure Path runs locked. (#639)
84
+ - **Ship opens its run straight after the lock.** Step 1 sets up the worktree and runs `bkit workflows start` before any tracker write or preflight, so every later failure has a place to keep its record. Step 14 copies `ship-summary.md` to the outbox before the close removes the worktree, so the final message shows it. Step names are unchanged. (#639)
85
+ - **A design / plan close keeps the branch's ledger rows.** The `-X ours` squash dropped a row the branch added to a ledger without `merge=union` (a consumer's `.bkit/friction.jsonl`); the close now appends it back. The main checkout is never written: the `close-transport` row is logged instead, unless the run's own checkout is the branch. A PR whose state could not be read is retried like an open one. (#639)
86
+ - **Ship's compliance grade reads the squash commit.** The grade checks the squash's subject and `squash~1..squash`, not the worktree's last commit, so a `[skip ci]` log commit there no longer fails `skip-ci-not-head`. (#639)
87
+ - **The roadmap mirror reports a failed commit.** A build / debug mirror attempt that committed nothing (append or commit failed) is reported as not mirrored, never as landed. (#639)
88
+ - **`gh` answering HTTP 403 hands the call to the GitHub MCP.** Like a missing `gh` or a failed login, so a cloud close needing the PR route switches tools instead of stopping. (#639)
89
+ - **`bkit upgrade` deletes a leftover `.bkit/.dev.lock`.** Nothing reads it any more. Registered in `docs/migrations.md`. (#639)
90
+ - **A tracker switch updates every installed host.** `bkit install --tracker=<name>` now works with no host flag, as `.bkit/install.md` says, and re-renders every installed host's commands, agents and MCP entries. Before, `bkit install --claude --tracker=github` left Cursor, Codex, Antigravity and opencode on the old tracker, and `bkit check` then failed.
91
+ - **Claude Code runs Linear writes without asking.** The shipped `.claude/settings.json` allow list gains `mcp__linear__*`, the tools of the `linear` server in `.mcp.json` that workflows call (`save_issue`, `save_comment`). It held only `mcp__claude_ai_Linear__*`, so every Linear write stopped for permission.
92
+ - **Docs and CI templates never name `dev` as the production branch.** `{{DEFAULT_BRANCH}}` reads `origin/HEAD`, but a remote whose default branch is `dev` now gets `main`, the same as a checkout with no `origin/HEAD`. Before, such a repo's `docs/testing.md` read "`dev`/`dev` push", and the bytes changed with whether `origin/HEAD` was set, so `bkit check` passed on one machine and failed on another.
93
+ - **`bkit upgrade --help` says which files can conflict.** Only a whole file you edited since bkit wrote it; rendered agents, commands, skills and `.bkit/*.md` are always re-rendered, and `bkit check` flags an edit to one. `bkit branches --help` no longer offers the removed `switch`, and the tracker help says the `github` MCP entry stays on every switch.
10
94
 
11
95
  ## [5.3.0] — 2026-10-19
12
96