@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
@@ -1,16 +1,13 @@
1
- // bkit locks acquire|release — the per-feature workflow lock and the dev lock.
1
+ // bkit locks acquire|release — the per-feature workflow lock.
2
2
  //
3
- // workflow `docs/plans/{month}/logs/{fid}/.lock`: one phase workflow per feature
4
- // at a time. A lock left behind is reclaimed as soon as its holder is
5
- // idle: its run is not IN_PROGRESS, or stepped no sooner than 30 minutes
6
- // ago. The lock file's own age is not checked.
7
- // dev `.bkit/.dev.lock` in the main checkout: held across every checkout /
8
- // commit / push of `dev` there. Acquire waits a bounded time; the shell
9
- // releases it from `trap ... EXIT`.
3
+ // `docs/plans/{month}/logs/{fid}/.lock` in the main checkout: one phase workflow
4
+ // per feature at a time. A lock left behind is reclaimed as soon as its holder is
5
+ // idle: its run is not IN_PROGRESS, or stepped no sooner than 30 minutes ago. The
6
+ // lock file's own age is not checked.
10
7
  //
11
- // Both write one line, `{at} {workflow} {fid} {token}`. Release removes only a lock
12
- // this caller owns (same token, else same workflow and feature), so a Failure Path
13
- // that never got the lock cannot delete the holder's.
8
+ // The lock holds one line, `{at} {workflow} {fid} {token}`. Release removes only a
9
+ // lock this caller owns (same token, else same workflow and feature), so a Failure
10
+ // Path that never got the lock cannot delete the holder's.
14
11
 
15
12
  import { randomBytes } from "node:crypto";
16
13
  import * as fs from "node:fs";
@@ -26,7 +23,6 @@ import {
26
23
  import {
27
24
  CommandError,
28
25
  EXIT,
29
- git,
30
26
  parseJson,
31
27
  repoRoot,
32
28
  statusRelPath,
@@ -35,13 +31,10 @@ import {
35
31
  type FlagSpec,
36
32
  type RunContext,
37
33
  } from "../lib.js";
38
- import { TIMEOUTS } from "../../shared/timeouts.js";
39
34
  import { str } from "./status.js";
40
35
 
41
36
  /** A workflow lock whose holder shows no sign of life for this long is stale. */
42
37
  export const WORKFLOW_LOCK_IDLE_S = 1800;
43
- /** Seconds between dev-lock attempts while it is busy. */
44
- export const DEV_LOCK_POLL_S = 5;
45
38
 
46
39
  /** Exit code: the feature has logs in more than one month bucket. */
47
40
  export const EXIT_SPLIT_BUCKET = 7;
@@ -50,7 +43,7 @@ export const EXIT_NOT_OWNER = 4;
50
43
  /** Exit code: the lock file is still there after removing it. */
51
44
  export const EXIT_REMOVE_FAILED = 5;
52
45
 
53
- const KINDS = ["workflow", "dev"] as const;
46
+ const KINDS = ["workflow"] as const;
54
47
  type Kind = (typeof KINDS)[number];
55
48
 
56
49
  // ---------------------------------------------------------------------------
@@ -92,20 +85,9 @@ export function resolveMonth(root: string, fid: string, month: string | undefine
92
85
  return buckets[0] ?? utcMonth();
93
86
  }
94
87
 
95
- /**
96
- * Root the workflow books its logs under: the main checkout, except ship in a
97
- * runtime that does not push to dev, which books on the branch being shipped.
98
- */
99
- export function lockRoot(cwd: string, workflow: string, devPushes: boolean): string {
100
- const root = repoRoot(cwd);
101
- if (workflow !== "ship" || devPushes) return root;
102
- return git(cwd, ["rev-parse", "--show-toplevel"]) ?? root;
103
- }
104
-
105
- export const workflowLockPath = (bookRoot: string, month: string, fid: string) =>
106
- path.join(bookRoot, "docs", "plans", month, "logs", fid, ".lock");
107
-
108
- export const devLockPath = (root: string) => path.join(root, ".bkit", ".dev.lock");
88
+ /** The feature's workflow lock, in the main checkout `root` (gitignored). */
89
+ export const workflowLockPath = (root: string, month: string, fid: string) =>
90
+ path.join(root, "docs", "plans", month, "logs", fid, ".lock");
109
91
 
110
92
  // ---------------------------------------------------------------------------
111
93
  // Lock file
@@ -127,7 +109,7 @@ export function readHolder(file: string): Holder | undefined {
127
109
  }
128
110
 
129
111
  /** Create `file` only if absent (`set -C`); false when someone else holds it. */
130
- function tryCreate(file: string, line: string): boolean {
112
+ export function tryCreate(file: string, line: string): boolean {
131
113
  fs.mkdirSync(path.dirname(file), { recursive: true });
132
114
  const fd = openExclusive(file);
133
115
  if (fd === undefined) return false;
@@ -146,11 +128,6 @@ function openExclusive(file: string): number | undefined {
146
128
  }
147
129
  }
148
130
 
149
- const ageSeconds = (file: string, now: number): number | undefined => {
150
- const st = fs.statSync(file, { throwIfNoEntry: false });
151
- return st === undefined ? undefined : Math.floor((now - st.mtimeMs) / 1000);
152
- };
153
-
154
131
  const newToken = () => randomBytes(4).toString("hex");
155
132
 
156
133
  const lockLine = (workflow: string, fid: string, token: string) =>
@@ -177,7 +154,6 @@ export interface WorkflowLockResult {
177
154
  /** Why a held workflow lock is still live, or why it may be reclaimed. */
178
155
  function liveReason(
179
156
  root: string,
180
- bookRoot: string,
181
157
  month: string,
182
158
  fid: string,
183
159
  holder: Holder,
@@ -185,7 +161,7 @@ function liveReason(
185
161
  ): { live: string } | { reason: "finished" | "stale" | "orphaned" } {
186
162
  const rel = statusRelPath(month, fid);
187
163
  const worktreeCopy = path.join(root, ".worktrees", fid, rel);
188
- const own = fs.existsSync(worktreeCopy) ? worktreeCopy : path.join(bookRoot, rel);
164
+ const own = fs.existsSync(worktreeCopy) ? worktreeCopy : path.join(root, rel);
189
165
  const run =
190
166
  holder.workflow === undefined ? undefined : lastRun(readRunsLenient(own), holder.workflow);
191
167
  const lastAt = run?.steps.at(-1)?.at;
@@ -219,19 +195,17 @@ export function acquireWorkflowLock(opts: {
219
195
  workflow: string;
220
196
  fid: string;
221
197
  month?: string;
222
- devPushes: boolean;
223
198
  log: (m: string) => void;
224
199
  }): WorkflowLockResult {
225
200
  const root = repoRoot(opts.cwd);
226
201
  const month = resolveMonth(root, opts.fid, opts.month);
227
- const bookRoot = lockRoot(opts.cwd, opts.workflow, opts.devPushes);
228
- const file = workflowLockPath(bookRoot, month, opts.fid);
202
+ const file = workflowLockPath(root, month, opts.fid);
229
203
  const token = newToken();
230
204
  const line = lockLine(opts.workflow, opts.fid, token);
231
205
  if (tryCreate(file, line)) return { path: file, month, token, reclaimed: null };
232
206
 
233
207
  const holder = readHolder(file) ?? { line: "" };
234
- const verdict = liveReason(root, bookRoot, month, opts.fid, holder, Date.now());
208
+ const verdict = liveReason(root, month, opts.fid, holder, Date.now());
235
209
  if ("live" in verdict) {
236
210
  throw new CommandError(
237
211
  EXIT.NO,
@@ -244,47 +218,6 @@ export function acquireWorkflowLock(opts: {
244
218
  return { path: file, month, token, reclaimed: { holder: holder.line, reason: verdict.reason } };
245
219
  }
246
220
 
247
- // ---------------------------------------------------------------------------
248
- // Dev lock
249
- // ---------------------------------------------------------------------------
250
-
251
- const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
252
-
253
- export async function acquireDevLock(opts: {
254
- cwd: string;
255
- workflow: string;
256
- fid: string;
257
- deadlineS: number;
258
- log: (m: string) => void;
259
- }): Promise<{ path: string; token: string; reclaimed: string | null; waitedS: number }> {
260
- const file = devLockPath(repoRoot(opts.cwd));
261
- const token = newToken();
262
- const start = Date.now();
263
- const deadline = start + opts.deadlineS * 1000;
264
- let reclaimed: string | null = null;
265
- for (;;) {
266
- if (tryCreate(file, lockLine(opts.workflow, opts.fid, token))) {
267
- return { path: file, token, reclaimed, waitedS: Math.round((Date.now() - start) / 1000) };
268
- }
269
- const now = Date.now();
270
- const age = ageSeconds(file, now);
271
- if (age === undefined) continue; // released between the attempt and the stat
272
- if (age >= TIMEOUTS.SHIP_DEV_LOCK_STALE_S) {
273
- reclaimed = readHolder(file)?.line ?? "";
274
- opts.log(`reclaiming stale dev lock (${age}s old): ${reclaimed}`);
275
- fs.rmSync(file, { force: true });
276
- continue;
277
- }
278
- if (now >= deadline) {
279
- throw new CommandError(
280
- EXIT.NO,
281
- `dev lock held by: ${readHolder(file)?.line ?? "?"} — serialise this run or use a separate clone`,
282
- );
283
- }
284
- await sleep(Math.min(DEV_LOCK_POLL_S * 1000, deadline - now));
285
- }
286
- }
287
-
288
221
  // ---------------------------------------------------------------------------
289
222
  // Release
290
223
  // ---------------------------------------------------------------------------
@@ -324,7 +257,7 @@ const KIND_FLAG: FlagSpec = {
324
257
  name: "kind",
325
258
  type: "string",
326
259
  required: true,
327
- help: "workflow (per-feature .lock) or dev (.bkit/.dev.lock)",
260
+ help: "workflow (the per-feature .lock)",
328
261
  };
329
262
  const LOCK_WORKFLOW_FLAG: FlagSpec = {
330
263
  name: "workflow",
@@ -338,83 +271,41 @@ const MONTH_FLAG: FlagSpec = {
338
271
  type: "string",
339
272
  help: "workflow kind: month bucket YYYYMM (default: the feature's bucket, else this UTC month)",
340
273
  };
341
- const DEV_PUSHES_FLAG: FlagSpec = {
342
- name: "dev-pushes",
343
- type: "boolean",
344
- help: "ship only: this runtime pushes to dev (lock lives in the main checkout)",
345
- };
346
274
 
347
275
  function kindOf(ctx: RunContext): Kind {
348
276
  const kind = String(ctx.flags.kind);
349
277
  if (!(KINDS as readonly string[]).includes(kind))
350
- throw new CommandError(EXIT.USAGE, "--kind must be workflow or dev");
278
+ throw new CommandError(EXIT.USAGE, "--kind must be workflow");
351
279
  return kind as Kind;
352
280
  }
353
281
 
354
- function deadlineOf(ctx: RunContext): number {
355
- const raw = str(ctx.flags.deadline);
356
- if (raw === undefined) return TIMEOUTS.SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S;
357
- if (!/^[0-9]+$/.test(raw))
358
- throw new CommandError(EXIT.USAGE, `--deadline must be whole seconds, got "${raw}"`);
359
- return Number(raw);
360
- }
361
-
362
282
  export const locksCommand: CommandSpec = {
363
283
  noun: "locks",
364
- summary: "Acquire and release the per-feature workflow lock and the dev lock.",
284
+ summary: "Acquire and release the per-feature workflow lock.",
365
285
  verbs: {
366
286
  acquire: {
367
- summary: "Take a lock: workflow (reclaims a dead holder's) or dev (bounded wait).",
368
- flags: [
369
- KIND_FLAG,
370
- LOCK_WORKFLOW_FLAG,
371
- FID_FLAG,
372
- MONTH_FLAG,
373
- DEV_PUSHES_FLAG,
374
- {
375
- name: "deadline",
376
- type: "string",
377
- help: `dev kind: seconds to wait for a busy lock (default ${TIMEOUTS.SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S})`,
378
- },
379
- ],
287
+ summary: "Take the workflow lock, reclaiming a dead holder's.",
288
+ flags: [KIND_FLAG, LOCK_WORKFLOW_FLAG, FID_FLAG, MONTH_FLAG],
380
289
  output: {
381
- kind: "workflow or dev",
290
+ kind: "workflow",
382
291
  path: "absolute path of the lock file",
383
292
  token: "this holder's token; pass it to release",
384
- month: "workflow kind: the month bucket (null for dev)",
385
- reclaimed:
386
- "workflow kind: {holder, reason: finished|stale|orphaned}; dev kind: the stale line; null when none",
387
- waitedS: "dev kind: seconds spent waiting (null for workflow)",
293
+ month: "the month bucket",
294
+ reclaimed: "{holder, reason: finished|stale|orphaned}; null when none",
388
295
  },
389
296
  exitCodes: {
390
- [EXIT_SPLIT_BUCKET]: "workflow kind: the feature has logs in more than one month bucket",
297
+ [EXIT_SPLIT_BUCKET]: "the feature has logs in more than one month bucket",
391
298
  },
392
- run: async (ctx) => {
299
+ run: (ctx) => {
393
300
  const kind = kindOf(ctx);
394
- const workflow = String(ctx.flags.workflow);
395
- const fid = String(ctx.flags.fid);
396
- if (kind === "workflow") {
397
- if (ctx.flags.deadline !== undefined)
398
- throw new CommandError(EXIT.USAGE, "--deadline applies to --kind=dev only");
399
- const lock = acquireWorkflowLock({
400
- cwd: ctx.cwd,
401
- workflow,
402
- fid,
403
- month: str(ctx.flags.month),
404
- devPushes: ctx.flags.devPushes === true,
405
- log: ctx.log,
406
- });
407
- ctx.emit({ kind, ...lock, waitedS: null });
408
- return EXIT.OK;
409
- }
410
- const lock = await acquireDevLock({
301
+ const lock = acquireWorkflowLock({
411
302
  cwd: ctx.cwd,
412
- workflow,
413
- fid,
414
- deadlineS: deadlineOf(ctx),
303
+ workflow: String(ctx.flags.workflow),
304
+ fid: String(ctx.flags.fid),
305
+ month: str(ctx.flags.month),
415
306
  log: ctx.log,
416
307
  });
417
- ctx.emit({ kind, ...lock, month: null });
308
+ ctx.emit({ kind, ...lock });
418
309
  return EXIT.OK;
419
310
  },
420
311
  },
@@ -425,7 +316,6 @@ export const locksCommand: CommandSpec = {
425
316
  LOCK_WORKFLOW_FLAG,
426
317
  FID_FLAG,
427
318
  MONTH_FLAG,
428
- DEV_PUSHES_FLAG,
429
319
  {
430
320
  name: "token",
431
321
  type: "string",
@@ -433,15 +323,14 @@ export const locksCommand: CommandSpec = {
433
323
  },
434
324
  ],
435
325
  output: {
436
- kind: "workflow or dev",
326
+ kind: "workflow",
437
327
  path: "absolute path of the lock file",
438
328
  existed: "a lock file was there",
439
329
  released: "this call removed it",
440
330
  heldBy: "the other owner's lock line when it was left in place, else null",
441
331
  },
442
332
  exitCodes: {
443
- [EXIT_SPLIT_BUCKET]:
444
- "workflow kind without --month: the feature has logs in more than one month bucket",
333
+ [EXIT_SPLIT_BUCKET]: "no --month and the feature has logs in more than one month bucket",
445
334
  [EXIT_NOT_OWNER]: "the lock belongs to another owner and was left in place",
446
335
  [EXIT_REMOVE_FAILED]: "the lock file is still there after removing it",
447
336
  },
@@ -453,14 +342,11 @@ export const locksCommand: CommandSpec = {
453
342
  token: str(ctx.flags.token),
454
343
  };
455
344
  const root = repoRoot(ctx.cwd);
456
- const file =
457
- kind === "dev"
458
- ? devLockPath(root)
459
- : workflowLockPath(
460
- lockRoot(ctx.cwd, who.workflow, ctx.flags.devPushes === true),
461
- resolveMonth(root, who.fid, str(ctx.flags.month)),
462
- who.fid,
463
- );
345
+ const file = workflowLockPath(
346
+ root,
347
+ resolveMonth(root, who.fid, str(ctx.flags.month)),
348
+ who.fid,
349
+ );
464
350
  const { removeFailed, ...result } = releaseLock(file, who);
465
351
  ctx.emit({ kind, ...result });
466
352
  if (removeFailed) {
@@ -169,11 +169,13 @@ function refFlag(value: FlagValue, flag: string): string {
169
169
  const FID_FORMAT: Record<IssueTracker, RegExp> = {
170
170
  github: /^[0-9]+-[a-z0-9-]+$/,
171
171
  linear: /^[a-z]+-[0-9]+-[a-z0-9-]+$/,
172
+ jira: /^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$/,
172
173
  none: /^[a-z0-9][a-z0-9-]*$/,
173
174
  };
174
175
  const ISSUE_FORMAT: Record<Exclude<IssueTracker, "none">, RegExp> = {
175
176
  github: /^[0-9]+$/,
176
177
  linear: /^[A-Z]+-[0-9]+$/,
178
+ jira: /^[A-Z][A-Z0-9]+-[0-9]+$/,
177
179
  };
178
180
 
179
181
  /** The PR-body marker line for this tracker (`.bkit/trackers.md` `pr-body-marker`). */
@@ -620,17 +622,26 @@ export function crossCheckFile(
620
622
  file: string,
621
623
  transport: string,
622
624
  log: (m: string) => void,
625
+ ): { ok: boolean; runtimeGithubCli: boolean | null; transport: string; fallbackRows: number } {
626
+ return crossCheckRows(readStatusRows(file), file, transport, log);
627
+ }
628
+
629
+ /** crossCheckFile over rows already read; `label` names where they came from. */
630
+ export function crossCheckRows(
631
+ rows: StatusRow[],
632
+ label: string,
633
+ transport: string,
634
+ log: (m: string) => void,
623
635
  ): { ok: boolean; runtimeGithubCli: boolean | null; transport: string; fallbackRows: number } {
624
636
  if (!TRANSPORTS.includes(transport)) {
625
637
  throw new CommandError(EXIT.USAGE, `--transport must be ${TRANSPORTS.join(", ")}`);
626
638
  }
627
- const rows = readStatusRows(file);
628
639
  const runtimeGithubCli = capability(lastRow(rows, "runtime-resolved")?.runtimeGithubCli);
629
640
  const fallbackRows = rows.filter((r) => r.type === "transport-fallback").length;
630
641
  const violated = runtimeGithubCli === false && transport === "mcp" && fallbackRows === 0;
631
642
  if (violated) {
632
643
  log(
633
- `runtime-resolved logged runtimeGithubCli=false and this close used transport mcp, but no transport-fallback row exists in ${file}`,
644
+ `runtime-resolved logged runtimeGithubCli=false and this close used transport mcp, but no transport-fallback row exists in ${label}`,
634
645
  );
635
646
  }
636
647
  return { ok: !violated, runtimeGithubCli, transport, fallbackRows };
@@ -778,7 +789,7 @@ export const prsCommand: CommandSpec = {
778
789
  {
779
790
  name: "issue",
780
791
  type: "string",
781
- help: "issue id for the marker (github: 123 or #123; linear: ABC-123)",
792
+ help: "issue id for the marker (github: 123 or #123; linear / jira: ABC-123)",
782
793
  },
783
794
  BASE_FLAG,
784
795
  HEAD_FLAG,
@@ -13,6 +13,7 @@ import * as path from "node:path";
13
13
  import { parseRemoteUrlToSlug } from "../../ledgers/telemetry.js";
14
14
  import { DEV, EXIT, git, repoRoot, runGit, runTool, type CommandSpec } from "../lib.js";
15
15
  import { bkitVersionStatus } from "../../shared/bkit-latest.js";
16
+ import { readBkitConfig, trackerScope } from "../../shared/settings.js";
16
17
 
17
18
  /** Exit code: neither gh nor the origin remote named an owner/repo. */
18
19
  export const EXIT_NO_REPO = 3;
@@ -130,6 +131,10 @@ export const repoCommand: CommandSpec = {
130
131
  bkitOutdated:
131
132
  "true when bkitVersion is older than bkitLatest (null when either is unknown)",
132
133
  bkitAdvisory: "one line to show the user when bkitOutdated, else null",
134
+ trackerTeam: "package.json bkit.linear.team under linear, else null",
135
+ trackerProject:
136
+ "package.json bkit.linear.project under linear, bkit.jira.project under jira, else null",
137
+ trackerSite: "package.json bkit.jira.site under jira (the MCP cloudId), else null",
133
138
  },
134
139
  exitCodes: {
135
140
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -179,6 +184,7 @@ export const repoCommand: CommandSpec = {
179
184
  bkitLatest: latest.latest,
180
185
  bkitOutdated: latest.outdated,
181
186
  bkitAdvisory: latest.advisory,
187
+ ...trackerScope(readBkitConfig(root)),
182
188
  });
183
189
  if (branch === null && ctx.flags.allowDetached !== true) {
184
190
  ctx.log("HEAD is detached — no current branch");
@@ -1,6 +1,6 @@
1
1
  // bkit roadmap fold|feature|mirror — rewrite the generated region of
2
2
  // docs/roadmap.md from .bkit/issues.jsonl, its SOLE input; append a feature's
3
- // row; and copy a build / debug close's row to dev under the dev lock.
3
+ // row; and copy a build / debug close's row to dev through a throwaway checkout.
4
4
  //
5
5
  // The status block is a pure projection of the ledger, re-rendered in full, so
6
6
  // a close never parses the board back. The two `## Notes` blocks and the
@@ -31,7 +31,7 @@ import {
31
31
  type CommandSpec,
32
32
  type RunContext,
33
33
  } from "../lib.js";
34
- import { acquireDevLock, releaseLock } from "./locks.js";
34
+ import { landDir, pushToDev } from "../land.js";
35
35
  import { str } from "./status.js";
36
36
 
37
37
  /** Roadmap status each workflow's close moves the feature to. */
@@ -60,6 +60,10 @@ const NOTES_POST_PLACEHOLDER = "## Notes\n\n_(end of the board — yours, never
60
60
  const BANNER =
61
61
  "> Generated tables — do not hand-edit the `bkit` tables; append to `.bkit/issues.jsonl` instead (an `ABANDONED` row hides a FID from every section). `## Notes` blocks are yours and are never overwritten. Everything above the first marker is also yours. notes-post is last. Analysis list length: `package.json` key `bkit.roadmapNext` (positive integer; absent or invalid → 25).";
62
62
 
63
+ /** Fixed related-utilities line; `@bkit-audit-generate` ends every run with the same text. */
64
+ export const RELATED_UTILITIES =
65
+ "> Related utilities, run on demand: `@bkit-utility-update-roadmap` ranks the next best items in `docs/roadmap.md`; `@bkit-utility-update-tracker` brings tracker issues in line with the tracker rules; `@bkit-utility-update-deferrals` and `@bkit-utility-update-failures` close ledger rows the code already resolved; `@bkit-utility-update-decisions`, `@bkit-utility-update-knowledge` and `@bkit-utility-update-documentation` correct ledgers and docs the code has since contradicted.";
66
+
63
67
  /** Newest SHIPPED rows on the board; older ones stay in the ledger. */
64
68
  export const SHIPPED_ON_BOARD = 10;
65
69
 
@@ -133,7 +137,7 @@ function table(rows: Row[]): string[] {
133
137
  }
134
138
 
135
139
  export function statusBlock(p: Projection, now: string): string {
136
- const out = [BANNER, "", "## bkit", "", `_(refreshed ${now})_`];
140
+ const out = [BANNER, "", RELATED_UTILITIES, "", "## bkit", "", `_(refreshed ${now})_`];
137
141
  for (const [bucket, , heading] of SECTIONS) out.push("", heading, "", ...table(p[bucket]));
138
142
  return out.join("\n");
139
143
  }
@@ -414,17 +418,14 @@ function feature(ctx: RunContext): number {
414
418
  return ctx.flags.strict === true && !r.appended ? EXIT.NO : EXIT.OK;
415
419
  }
416
420
 
417
- /** Seconds the mirror waits for a busy dev lock before skipping. */
418
- export const MIRROR_DEV_LOCK_DEADLINE_S = 60;
419
-
420
421
  const ROADMAP_FILES = [".bkit/issues.jsonl", "docs/roadmap.md"];
421
422
 
422
423
  /**
423
- * Build / debug close: append the feature row in the worktree, then copy the
424
- * SAME row to `dev` in the main checkout under the dev lock — checkout dev,
425
- * fast-forward, append, commit the two roadmap files, push, return to the prior
426
- * branch. Skipped in adopt mode (the worktree IS the main checkout) and when the
427
- * dev lock stays busy. Fail-open throughout: the feat-side row is already written.
424
+ * Build / debug close: append the feature row in the worktree, then land the
425
+ * SAME row on `dev` through a throwaway origin/dev checkout (`pushToDev`). The
426
+ * main checkout is never touched. Skipped when the run's own checkout is on dev
427
+ * (the row rides that branch's commit). Fail-open throughout: the feat-side row
428
+ * is already written and reaches dev with ship's merge.
428
429
  */
429
430
  async function mirror(ctx: RunContext): Promise<number> {
430
431
  const workflow = String(ctx.flags.workflow);
@@ -438,47 +439,45 @@ async function mirror(ctx: RunContext): Promise<number> {
438
439
  ctx.emit({ row: feat.row, appended: feat.appended, mirrored, skipped });
439
440
  return EXIT.OK;
440
441
  };
441
- if (path.resolve(wt) === path.resolve(root)) return done(false, "adopt mode");
442
-
443
- let lock: { path: string; token: string };
444
- try {
445
- lock = await acquireDevLock({
446
- cwd: root,
447
- workflow,
448
- fid,
449
- deadlineS: MIRROR_DEV_LOCK_DEADLINE_S,
450
- log: ctx.log,
451
- });
452
- } catch (err) {
453
- // A busy lock skips the mirror; it never fails the close.
454
- return done(false, `dev lock busy: ${(err as Error).message}`);
455
- }
456
- try {
457
- const prior = git(root, ["branch", "--show-current"]) ?? "";
458
- if (
459
- !runGit(root, ["checkout", DEV]).ok ||
460
- !runGit(root, ["pull", "--ff-only", "origin", DEV]).ok
461
- ) {
462
- if (prior) runGit(root, ["checkout", prior]);
463
- return done(false, "dev checkout / pull failed");
464
- }
465
- const onDev = appendFeature(root, { row: JSON.stringify(feat.row) }, ctx.log);
466
- if (!onDev.appended) ctx.log("roadmap row skipped on dev");
467
- runGit(root, ["add", "--", ...ROADMAP_FILES]);
468
- runGit(root, [
469
- "commit",
470
- "--allow-empty",
471
- "-m",
472
- `docs(${fid}): ${workflow} roadmap update bkit [skip ci]`,
473
- "--",
474
- ...ROADMAP_FILES,
475
- ]);
476
- const pushed = runGit(root, ["push", "origin", DEV]).ok;
477
- if (!pushed) ctx.log("dev push failed — feat-side row already written");
478
- if (prior) runGit(root, ["checkout", prior]);
479
- return done(pushed, pushed ? null : "dev push failed");
480
- } finally {
481
- releaseLock(lock.path, { workflow, fid, token: lock.token });
442
+ if (git(wt, ["branch", "--show-current"]) === DEV) return done(false, "on dev");
443
+
444
+ // A build that commits nothing pushes origin/dev back to itself, which git
445
+ // reports as success — so a landing counts only when this attempt committed.
446
+ let committed = "";
447
+ const res = await pushToDev({
448
+ root,
449
+ dir: landDir(root, fid),
450
+ build: (dir) => {
451
+ committed = "";
452
+ if (!appendFeature(dir, { row: JSON.stringify(feat.row) }, ctx.log).appended) {
453
+ committed = "row not appended on dev";
454
+ return;
455
+ }
456
+ runGit(dir, ["add", "--", ...ROADMAP_FILES]);
457
+ const made = runGit(dir, [
458
+ "commit",
459
+ "-m",
460
+ `docs(${fid}): ${workflow} roadmap update bkit [skip ci]`,
461
+ "--",
462
+ ...ROADMAP_FILES,
463
+ ]);
464
+ if (!made.ok) committed = `roadmap commit failed: ${made.stderr || made.stdout}`;
465
+ },
466
+ log: ctx.log,
467
+ });
468
+ switch (res.kind) {
469
+ case "landed":
470
+ return committed ? done(false, committed) : done(true, null);
471
+ case "refused":
472
+ return done(false, `dev push refused: ${res.stderr}`);
473
+ case "push-failed":
474
+ return done(false, `dev push failed: ${res.stderr}`);
475
+ case "exhausted":
476
+ return done(false, `dev moved before each of ${res.attempts} pushes`);
477
+ case "fetch-failed":
478
+ return done(false, `fetch of dev failed: ${res.stderr}`);
479
+ case "setup-failed":
480
+ return done(false, `throwaway checkout failed: ${res.stderr}`);
482
481
  }
483
482
  }
484
483
 
@@ -559,7 +558,7 @@ export const roadmapCommand: CommandSpec = {
559
558
  },
560
559
  mirror: {
561
560
  summary:
562
- "Build / debug close: append the feature row in the worktree, then the same row on dev under the dev lock (fail-open).",
561
+ "Build / debug close: append the feature row in the worktree, then land the same row on dev through a throwaway origin/dev checkout (fail-open).",
563
562
  flags: [
564
563
  { name: "workflow", type: "string", required: true, help: "build | debug" },
565
564
  { name: "fid", type: "string", required: true, help: "feature id (the row's key)" },
@@ -569,7 +568,7 @@ export const roadmapCommand: CommandSpec = {
569
568
  appended: "false when the worktree ledger could not be written",
570
569
  mirrored: "the row was committed and pushed on dev",
571
570
  skipped:
572
- "why the dev side was skipped: adopt mode | dev lock busy | dev checkout / pull failed | dev push failed (null when mirrored)",
571
+ "why the dev side was skipped: on dev | row not appended on dev | dev push refused | dev moved before each push | fetch of dev failed | throwaway checkout failed (null when mirrored)",
573
572
  },
574
573
  run: (ctx) => mirror(ctx),
575
574
  },
@@ -106,8 +106,9 @@ export function classify(env: NodeJS.ProcessEnv, root: string, log: (m: string)
106
106
 
107
107
  /**
108
108
  * Default capabilities per runtime. CLOUD_CURSOR matches GITHUB_ACTION on
109
- * purpose (isolated VM, real git, mints and pushes its own branch); a claude.ai
110
- * session's proxy only lets it push the current branch, so it gets neither.
109
+ * purpose (isolated VM, real git, mints and pushes its own branch). A claude.ai
110
+ * session gets neither: whether it may push dev can't be tested without making
111
+ * that push, and a wrong guess strands the session on a dev checkout.
111
112
  */
112
113
  const capable = (runtime: Runtime) =>
113
114
  runtime === "LOCAL" || runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR";