@cbartens/bkit 5.3.0 → 5.4.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 (128) hide show
  1. package/.bkit/README.md +3 -2
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +8 -2
  4. package/.bkit/core/.bkit/README.md +2 -1
  5. package/.bkit/core/.bkit/cloud.md +33 -33
  6. package/.bkit/core/.bkit/comparison.md +1 -1
  7. package/.bkit/core/.bkit/install.md +6 -5
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +4 -3
  10. package/.bkit/core/.bkit/prompts.md +4 -3
  11. package/.bkit/core/.bkit/providers.md +1 -1
  12. package/.bkit/core/.bkit/templates.md +35 -5
  13. package/.bkit/core/.bkit/trackers.md +7 -8
  14. package/.bkit/core/.bkit/workflows.md +106 -86
  15. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  16. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  17. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  23. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  25. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  26. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  28. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  29. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  30. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  32. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  34. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  36. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  37. package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
  38. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  39. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  40. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  43. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  44. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  47. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  48. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  49. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  50. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  51. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -0
  52. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  53. package/.bkit/core/engine/cli.ts +22 -15
  54. package/.bkit/core/engine/commands/comply.ts +25 -16
  55. package/.bkit/core/engine/commands/install/install.ts +11 -4
  56. package/.bkit/core/engine/commands/land.ts +156 -0
  57. package/.bkit/core/engine/commands/lib.ts +10 -8
  58. package/.bkit/core/engine/commands/registry.ts +2 -0
  59. package/.bkit/core/engine/commands/tips.ts +7 -3
  60. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  61. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  62. package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
  63. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  64. package/.bkit/core/engine/commands/workflow/prs.ts +11 -2
  65. package/.bkit/core/engine/commands/workflow/roadmap.ts +48 -53
  66. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  67. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  68. package/.bkit/core/engine/commands/workflow/steps.ts +24 -15
  69. package/.bkit/core/engine/commands/workflow/workflows.ts +433 -265
  70. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  71. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  72. package/.bkit/core/engine/install/modules/core.ts +15 -0
  73. package/.bkit/core/engine/install/placeholders.ts +13 -17
  74. package/.bkit/core/engine/shared/settings.ts +8 -0
  75. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  76. package/.bkit/core/prompts/bkit-audit-generate.md +47 -4
  77. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -1
  78. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -1
  79. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
  80. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -1
  81. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -1
  82. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +3 -3
  83. package/.bkit/core/workflows/bkit-auto.md +2 -2
  84. package/.bkit/core/workflows/bkit-build.md +7 -7
  85. package/.bkit/core/workflows/bkit-debug.md +11 -11
  86. package/.bkit/core/workflows/bkit-design.md +20 -11
  87. package/.bkit/core/workflows/bkit-plan.md +23 -13
  88. package/.bkit/core/workflows/bkit-ship.md +82 -93
  89. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  90. package/.bkit/shared/.claude/settings.json +1 -0
  91. package/.bkit/shared/docs/deployments.md +29 -25
  92. package/.bkit/shared/gitignore +1 -2
  93. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  94. package/.bkit/templates/.github/workflows/bkit-ci.yml +7 -2
  95. package/.bkit/templates/.husky/pre-commit +6 -0
  96. package/.bkit/templates/.husky/pre-push +7 -0
  97. package/.bkit/templates/.lintstagedrc.json +5 -1
  98. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  99. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  100. package/CHANGELOG.md +48 -0
  101. package/README.md +97 -96
  102. package/dist/checks/status-holes.js +0 -1
  103. package/dist/checks/tips/catalogue.js +14 -0
  104. package/dist/checks/tips/index.js +44 -28
  105. package/dist/cli.js +22 -16
  106. package/dist/commands/comply.js +20 -13
  107. package/dist/commands/install/install.js +10 -4
  108. package/dist/commands/land.js +129 -0
  109. package/dist/commands/lib.js +9 -6
  110. package/dist/commands/registry.js +2 -0
  111. package/dist/commands/tips.js +7 -3
  112. package/dist/commands/workflow/branches.js +300 -243
  113. package/dist/commands/workflow/disk.js +452 -0
  114. package/dist/commands/workflow/issues.js +63 -27
  115. package/dist/commands/workflow/locks.js +35 -130
  116. package/dist/commands/workflow/prs.js +5 -2
  117. package/dist/commands/workflow/roadmap.js +49 -56
  118. package/dist/commands/workflow/runtime.js +3 -2
  119. package/dist/commands/workflow/status.js +32 -12
  120. package/dist/commands/workflow/steps.js +18 -11
  121. package/dist/commands/workflow/workflows.js +388 -247
  122. package/dist/commands/workflow/workstreams.js +3 -2
  123. package/dist/commands/workflow/worktrees.js +11 -1
  124. package/dist/install/modules/core.js +13 -0
  125. package/dist/install/placeholders.js +13 -19
  126. package/dist/shared/settings.js +5 -0
  127. package/dist/shared/timeouts.js +8 -7
  128. package/package.json +1 -1
@@ -1,34 +1,28 @@
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
  import { randomBytes } from "node:crypto";
15
12
  import * as fs from "node:fs";
16
13
  import * as path from "node:path";
17
14
  import { fold, lastRun, statusTimestamp, } from "../../ledgers/status.js";
18
- import { CommandError, EXIT, git, parseJson, repoRoot, statusRelPath, utcMonth, } from "../lib.js";
19
- import { TIMEOUTS } from "../../shared/timeouts.js";
15
+ import { CommandError, EXIT, parseJson, repoRoot, statusRelPath, utcMonth, } from "../lib.js";
20
16
  import { str } from "./status.js";
21
17
  /** A workflow lock whose holder shows no sign of life for this long is stale. */
22
18
  export const WORKFLOW_LOCK_IDLE_S = 1800;
23
- /** Seconds between dev-lock attempts while it is busy. */
24
- export const DEV_LOCK_POLL_S = 5;
25
19
  /** Exit code: the feature has logs in more than one month bucket. */
26
20
  export const EXIT_SPLIT_BUCKET = 7;
27
21
  /** Exit code: the lock belongs to another owner and was left in place. */
28
22
  export const EXIT_NOT_OWNER = 4;
29
23
  /** Exit code: the lock file is still there after removing it. */
30
24
  export const EXIT_REMOVE_FAILED = 5;
31
- const KINDS = ["workflow", "dev"];
25
+ const KINDS = ["workflow"];
32
26
  // ---------------------------------------------------------------------------
33
27
  // Paths
34
28
  // ---------------------------------------------------------------------------
@@ -60,18 +54,8 @@ export function resolveMonth(root, fid, month) {
60
54
  }
61
55
  return buckets[0] ?? utcMonth();
62
56
  }
63
- /**
64
- * Root the workflow books its logs under: the main checkout, except ship in a
65
- * runtime that does not push to dev, which books on the branch being shipped.
66
- */
67
- export function lockRoot(cwd, workflow, devPushes) {
68
- const root = repoRoot(cwd);
69
- if (workflow !== "ship" || devPushes)
70
- return root;
71
- return git(cwd, ["rev-parse", "--show-toplevel"]) ?? root;
72
- }
73
- export const workflowLockPath = (bookRoot, month, fid) => path.join(bookRoot, "docs", "plans", month, "logs", fid, ".lock");
74
- export const devLockPath = (root) => path.join(root, ".bkit", ".dev.lock");
57
+ /** The feature's workflow lock, in the main checkout `root` (gitignored). */
58
+ export const workflowLockPath = (root, month, fid) => path.join(root, "docs", "plans", month, "logs", fid, ".lock");
75
59
  export function readHolder(file) {
76
60
  if (!fs.existsSync(file))
77
61
  return undefined;
@@ -80,7 +64,7 @@ export function readHolder(file) {
80
64
  return { line, at, workflow, fid, token };
81
65
  }
82
66
  /** Create `file` only if absent (`set -C`); false when someone else holds it. */
83
- function tryCreate(file, line) {
67
+ export function tryCreate(file, line) {
84
68
  fs.mkdirSync(path.dirname(file), { recursive: true });
85
69
  const fd = openExclusive(file);
86
70
  if (fd === undefined)
@@ -100,10 +84,6 @@ function openExclusive(file) {
100
84
  throw err;
101
85
  }
102
86
  }
103
- const ageSeconds = (file, now) => {
104
- const st = fs.statSync(file, { throwIfNoEntry: false });
105
- return st === undefined ? undefined : Math.floor((now - st.mtimeMs) / 1000);
106
- };
107
87
  const newToken = () => randomBytes(4).toString("hex");
108
88
  const lockLine = (workflow, fid, token) => `${statusTimestamp()} ${workflow} ${fid} ${token}`;
109
89
  /** The caller owns the lock: same token when it gave one, else same workflow and feature. */
@@ -113,10 +93,10 @@ export function owns(holder, who) {
113
93
  return holder.workflow === who.workflow && (holder.fid === undefined || holder.fid === who.fid);
114
94
  }
115
95
  /** Why a held workflow lock is still live, or why it may be reclaimed. */
116
- function liveReason(root, bookRoot, month, fid, holder, now) {
96
+ function liveReason(root, month, fid, holder, now) {
117
97
  const rel = statusRelPath(month, fid);
118
98
  const worktreeCopy = path.join(root, ".worktrees", fid, rel);
119
- const own = fs.existsSync(worktreeCopy) ? worktreeCopy : path.join(bookRoot, rel);
99
+ const own = fs.existsSync(worktreeCopy) ? worktreeCopy : path.join(root, rel);
120
100
  const run = holder.workflow === undefined ? undefined : lastRun(readRunsLenient(own), holder.workflow);
121
101
  const lastAt = run?.steps.at(-1)?.at;
122
102
  if (run?.status === "IN_PROGRESS" && lastAt) {
@@ -150,14 +130,13 @@ function readRunsLenient(file) {
150
130
  export function acquireWorkflowLock(opts) {
151
131
  const root = repoRoot(opts.cwd);
152
132
  const month = resolveMonth(root, opts.fid, opts.month);
153
- const bookRoot = lockRoot(opts.cwd, opts.workflow, opts.devPushes);
154
- const file = workflowLockPath(bookRoot, month, opts.fid);
133
+ const file = workflowLockPath(root, month, opts.fid);
155
134
  const token = newToken();
156
135
  const line = lockLine(opts.workflow, opts.fid, token);
157
136
  if (tryCreate(file, line))
158
137
  return { path: file, month, token, reclaimed: null };
159
138
  const holder = readHolder(file) ?? { line: "" };
160
- const verdict = liveReason(root, bookRoot, month, opts.fid, holder, Date.now());
139
+ const verdict = liveReason(root, month, opts.fid, holder, Date.now());
161
140
  if ("live" in verdict) {
162
141
  throw new CommandError(EXIT.NO, `workflow already running for ${opts.fid} (workflow=${holder.workflow ?? "?"}, ${verdict.live})`);
163
142
  }
@@ -167,36 +146,6 @@ export function acquireWorkflowLock(opts) {
167
146
  throw new CommandError(EXIT.NO, `lock contended for ${opts.fid}`);
168
147
  return { path: file, month, token, reclaimed: { holder: holder.line, reason: verdict.reason } };
169
148
  }
170
- // ---------------------------------------------------------------------------
171
- // Dev lock
172
- // ---------------------------------------------------------------------------
173
- const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
174
- export async function acquireDevLock(opts) {
175
- const file = devLockPath(repoRoot(opts.cwd));
176
- const token = newToken();
177
- const start = Date.now();
178
- const deadline = start + opts.deadlineS * 1000;
179
- let reclaimed = null;
180
- for (;;) {
181
- if (tryCreate(file, lockLine(opts.workflow, opts.fid, token))) {
182
- return { path: file, token, reclaimed, waitedS: Math.round((Date.now() - start) / 1000) };
183
- }
184
- const now = Date.now();
185
- const age = ageSeconds(file, now);
186
- if (age === undefined)
187
- continue; // released between the attempt and the stat
188
- if (age >= TIMEOUTS.SHIP_DEV_LOCK_STALE_S) {
189
- reclaimed = readHolder(file)?.line ?? "";
190
- opts.log(`reclaiming stale dev lock (${age}s old): ${reclaimed}`);
191
- fs.rmSync(file, { force: true });
192
- continue;
193
- }
194
- if (now >= deadline) {
195
- throw new CommandError(EXIT.NO, `dev lock held by: ${readHolder(file)?.line ?? "?"} — serialise this run or use a separate clone`);
196
- }
197
- await sleep(Math.min(DEV_LOCK_POLL_S * 1000, deadline - now));
198
- }
199
- }
200
149
  /**
201
150
  * Remove a lock this caller owns. Missing is fine (already released); another
202
151
  * owner's lock is left in place and reported.
@@ -219,7 +168,7 @@ const KIND_FLAG = {
219
168
  name: "kind",
220
169
  type: "string",
221
170
  required: true,
222
- help: "workflow (per-feature .lock) or dev (.bkit/.dev.lock)",
171
+ help: "workflow (the per-feature .lock)",
223
172
  };
224
173
  const LOCK_WORKFLOW_FLAG = {
225
174
  name: "workflow",
@@ -233,80 +182,39 @@ const MONTH_FLAG = {
233
182
  type: "string",
234
183
  help: "workflow kind: month bucket YYYYMM (default: the feature's bucket, else this UTC month)",
235
184
  };
236
- const DEV_PUSHES_FLAG = {
237
- name: "dev-pushes",
238
- type: "boolean",
239
- help: "ship only: this runtime pushes to dev (lock lives in the main checkout)",
240
- };
241
185
  function kindOf(ctx) {
242
186
  const kind = String(ctx.flags.kind);
243
187
  if (!KINDS.includes(kind))
244
- throw new CommandError(EXIT.USAGE, "--kind must be workflow or dev");
188
+ throw new CommandError(EXIT.USAGE, "--kind must be workflow");
245
189
  return kind;
246
190
  }
247
- function deadlineOf(ctx) {
248
- const raw = str(ctx.flags.deadline);
249
- if (raw === undefined)
250
- return TIMEOUTS.SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S;
251
- if (!/^[0-9]+$/.test(raw))
252
- throw new CommandError(EXIT.USAGE, `--deadline must be whole seconds, got "${raw}"`);
253
- return Number(raw);
254
- }
255
191
  export const locksCommand = {
256
192
  noun: "locks",
257
- summary: "Acquire and release the per-feature workflow lock and the dev lock.",
193
+ summary: "Acquire and release the per-feature workflow lock.",
258
194
  verbs: {
259
195
  acquire: {
260
- summary: "Take a lock: workflow (reclaims a dead holder's) or dev (bounded wait).",
261
- flags: [
262
- KIND_FLAG,
263
- LOCK_WORKFLOW_FLAG,
264
- FID_FLAG,
265
- MONTH_FLAG,
266
- DEV_PUSHES_FLAG,
267
- {
268
- name: "deadline",
269
- type: "string",
270
- help: `dev kind: seconds to wait for a busy lock (default ${TIMEOUTS.SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S})`,
271
- },
272
- ],
196
+ summary: "Take the workflow lock, reclaiming a dead holder's.",
197
+ flags: [KIND_FLAG, LOCK_WORKFLOW_FLAG, FID_FLAG, MONTH_FLAG],
273
198
  output: {
274
- kind: "workflow or dev",
199
+ kind: "workflow",
275
200
  path: "absolute path of the lock file",
276
201
  token: "this holder's token; pass it to release",
277
- month: "workflow kind: the month bucket (null for dev)",
278
- reclaimed: "workflow kind: {holder, reason: finished|stale|orphaned}; dev kind: the stale line; null when none",
279
- waitedS: "dev kind: seconds spent waiting (null for workflow)",
202
+ month: "the month bucket",
203
+ reclaimed: "{holder, reason: finished|stale|orphaned}; null when none",
280
204
  },
281
205
  exitCodes: {
282
- [EXIT_SPLIT_BUCKET]: "workflow kind: the feature has logs in more than one month bucket",
206
+ [EXIT_SPLIT_BUCKET]: "the feature has logs in more than one month bucket",
283
207
  },
284
- run: async (ctx) => {
208
+ run: (ctx) => {
285
209
  const kind = kindOf(ctx);
286
- const workflow = String(ctx.flags.workflow);
287
- const fid = String(ctx.flags.fid);
288
- if (kind === "workflow") {
289
- if (ctx.flags.deadline !== undefined)
290
- throw new CommandError(EXIT.USAGE, "--deadline applies to --kind=dev only");
291
- const lock = acquireWorkflowLock({
292
- cwd: ctx.cwd,
293
- workflow,
294
- fid,
295
- month: str(ctx.flags.month),
296
- devPushes: ctx.flags.devPushes === true,
297
- log: ctx.log,
298
- });
299
- ctx.emit({ kind, ...lock, waitedS: null });
300
- return EXIT.OK;
301
- }
302
- const lock = await acquireDevLock({
210
+ const lock = acquireWorkflowLock({
303
211
  cwd: ctx.cwd,
304
- workflow,
305
- fid,
306
- deadlineS: deadlineOf(ctx),
212
+ workflow: String(ctx.flags.workflow),
213
+ fid: String(ctx.flags.fid),
214
+ month: str(ctx.flags.month),
307
215
  log: ctx.log,
308
216
  });
309
- ctx.emit({ kind, ...lock, month: null });
217
+ ctx.emit({ kind, ...lock });
310
218
  return EXIT.OK;
311
219
  },
312
220
  },
@@ -317,7 +225,6 @@ export const locksCommand = {
317
225
  LOCK_WORKFLOW_FLAG,
318
226
  FID_FLAG,
319
227
  MONTH_FLAG,
320
- DEV_PUSHES_FLAG,
321
228
  {
322
229
  name: "token",
323
230
  type: "string",
@@ -325,14 +232,14 @@ export const locksCommand = {
325
232
  },
326
233
  ],
327
234
  output: {
328
- kind: "workflow or dev",
235
+ kind: "workflow",
329
236
  path: "absolute path of the lock file",
330
237
  existed: "a lock file was there",
331
238
  released: "this call removed it",
332
239
  heldBy: "the other owner's lock line when it was left in place, else null",
333
240
  },
334
241
  exitCodes: {
335
- [EXIT_SPLIT_BUCKET]: "workflow kind without --month: the feature has logs in more than one month bucket",
242
+ [EXIT_SPLIT_BUCKET]: "no --month and the feature has logs in more than one month bucket",
336
243
  [EXIT_NOT_OWNER]: "the lock belongs to another owner and was left in place",
337
244
  [EXIT_REMOVE_FAILED]: "the lock file is still there after removing it",
338
245
  },
@@ -344,9 +251,7 @@ export const locksCommand = {
344
251
  token: str(ctx.flags.token),
345
252
  };
346
253
  const root = repoRoot(ctx.cwd);
347
- const file = kind === "dev"
348
- ? devLockPath(root)
349
- : workflowLockPath(lockRoot(ctx.cwd, who.workflow, ctx.flags.devPushes === true), resolveMonth(root, who.fid, str(ctx.flags.month)), who.fid);
254
+ const file = workflowLockPath(root, resolveMonth(root, who.fid, str(ctx.flags.month)), who.fid);
350
255
  const { removeFailed, ...result } = releaseLock(file, who);
351
256
  ctx.emit({ kind, ...result });
352
257
  if (removeFailed) {
@@ -450,15 +450,18 @@ const TRANSPORTS = ["git", "gh", "mcp"];
450
450
  * a `git` close needs no `gh`, so a laptop that never ran `gh auth login` closes fine.
451
451
  */
452
452
  export function crossCheckFile(file, transport, log) {
453
+ return crossCheckRows(readStatusRows(file), file, transport, log);
454
+ }
455
+ /** crossCheckFile over rows already read; `label` names where they came from. */
456
+ export function crossCheckRows(rows, label, transport, log) {
453
457
  if (!TRANSPORTS.includes(transport)) {
454
458
  throw new CommandError(EXIT.USAGE, `--transport must be ${TRANSPORTS.join(", ")}`);
455
459
  }
456
- const rows = readStatusRows(file);
457
460
  const runtimeGithubCli = capability(lastRow(rows, "runtime-resolved")?.runtimeGithubCli);
458
461
  const fallbackRows = rows.filter((r) => r.type === "transport-fallback").length;
459
462
  const violated = runtimeGithubCli === false && transport === "mcp" && fallbackRows === 0;
460
463
  if (violated) {
461
- log(`runtime-resolved logged runtimeGithubCli=false and this close used transport mcp, but no transport-fallback row exists in ${file}`);
464
+ log(`runtime-resolved logged runtimeGithubCli=false and this close used transport mcp, but no transport-fallback row exists in ${label}`);
462
465
  }
463
466
  return { ok: !violated, runtimeGithubCli, transport, fallbackRows };
464
467
  }
@@ -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
@@ -19,7 +19,7 @@ import * as path from "node:path";
19
19
  import { compareTs, parse, resolveRepoSlug, validate } from "../../ledgers/telemetry.js";
20
20
  import { readBkitVersion } from "../../install/version-file.js";
21
21
  import { CommandError, DEV, EXIT, git, parseJson, repoRoot, runGit, } from "../lib.js";
22
- import { acquireDevLock, releaseLock } from "./locks.js";
22
+ import { landDir, pushToDev } from "../land.js";
23
23
  import { str } from "./status.js";
24
24
  /** Roadmap status each workflow's close moves the feature to. */
25
25
  export const FEATURE_STATUS = {
@@ -334,15 +334,13 @@ function feature(ctx) {
334
334
  ctx.emit({ ...r });
335
335
  return ctx.flags.strict === true && !r.appended ? EXIT.NO : EXIT.OK;
336
336
  }
337
- /** Seconds the mirror waits for a busy dev lock before skipping. */
338
- export const MIRROR_DEV_LOCK_DEADLINE_S = 60;
339
337
  const ROADMAP_FILES = [".bkit/issues.jsonl", "docs/roadmap.md"];
340
338
  /**
341
- * Build / debug close: append the feature row in the worktree, then copy the
342
- * SAME row to `dev` in the main checkout under the dev lock — checkout dev,
343
- * fast-forward, append, commit the two roadmap files, push, return to the prior
344
- * branch. Skipped in adopt mode (the worktree IS the main checkout) and when the
345
- * dev lock stays busy. Fail-open throughout: the feat-side row is already written.
339
+ * Build / debug close: append the feature row in the worktree, then land the
340
+ * SAME row on `dev` through a throwaway origin/dev checkout (`pushToDev`). The
341
+ * main checkout is never touched. Skipped when the run's own checkout is on dev
342
+ * (the row rides that branch's commit). Fail-open throughout: the feat-side row
343
+ * is already written and reaches dev with ship's merge.
346
344
  */
347
345
  async function mirror(ctx) {
348
346
  const workflow = String(ctx.flags.workflow);
@@ -356,51 +354,46 @@ async function mirror(ctx) {
356
354
  ctx.emit({ row: feat.row, appended: feat.appended, mirrored, skipped });
357
355
  return EXIT.OK;
358
356
  };
359
- if (path.resolve(wt) === path.resolve(root))
360
- return done(false, "adopt mode");
361
- let lock;
362
- try {
363
- lock = await acquireDevLock({
364
- cwd: root,
365
- workflow,
366
- fid,
367
- deadlineS: MIRROR_DEV_LOCK_DEADLINE_S,
368
- log: ctx.log,
369
- });
370
- }
371
- catch (err) {
372
- // A busy lock skips the mirror; it never fails the close.
373
- return done(false, `dev lock busy: ${err.message}`);
374
- }
375
- try {
376
- const prior = git(root, ["branch", "--show-current"]) ?? "";
377
- if (!runGit(root, ["checkout", DEV]).ok ||
378
- !runGit(root, ["pull", "--ff-only", "origin", DEV]).ok) {
379
- if (prior)
380
- runGit(root, ["checkout", prior]);
381
- return done(false, "dev checkout / pull failed");
382
- }
383
- const onDev = appendFeature(root, { row: JSON.stringify(feat.row) }, ctx.log);
384
- if (!onDev.appended)
385
- ctx.log("roadmap row skipped on dev");
386
- runGit(root, ["add", "--", ...ROADMAP_FILES]);
387
- runGit(root, [
388
- "commit",
389
- "--allow-empty",
390
- "-m",
391
- `docs(${fid}): ${workflow} roadmap update bkit [skip ci]`,
392
- "--",
393
- ...ROADMAP_FILES,
394
- ]);
395
- const pushed = runGit(root, ["push", "origin", DEV]).ok;
396
- if (!pushed)
397
- ctx.log("dev push failed — feat-side row already written");
398
- if (prior)
399
- runGit(root, ["checkout", prior]);
400
- return done(pushed, pushed ? null : "dev push failed");
401
- }
402
- finally {
403
- releaseLock(lock.path, { workflow, fid, token: lock.token });
357
+ if (git(wt, ["branch", "--show-current"]) === DEV)
358
+ return done(false, "on dev");
359
+ // A build that commits nothing pushes origin/dev back to itself, which git
360
+ // reports as success — so a landing counts only when this attempt committed.
361
+ let committed = "";
362
+ const res = await pushToDev({
363
+ root,
364
+ dir: landDir(root, fid),
365
+ build: (dir) => {
366
+ committed = "";
367
+ if (!appendFeature(dir, { row: JSON.stringify(feat.row) }, ctx.log).appended) {
368
+ committed = "row not appended on dev";
369
+ return;
370
+ }
371
+ runGit(dir, ["add", "--", ...ROADMAP_FILES]);
372
+ const made = runGit(dir, [
373
+ "commit",
374
+ "-m",
375
+ `docs(${fid}): ${workflow} roadmap update bkit [skip ci]`,
376
+ "--",
377
+ ...ROADMAP_FILES,
378
+ ]);
379
+ if (!made.ok)
380
+ committed = `roadmap commit failed: ${made.stderr || made.stdout}`;
381
+ },
382
+ log: ctx.log,
383
+ });
384
+ switch (res.kind) {
385
+ case "landed":
386
+ return committed ? done(false, committed) : done(true, null);
387
+ case "refused":
388
+ return done(false, `dev push refused: ${res.stderr}`);
389
+ case "push-failed":
390
+ return done(false, `dev push failed: ${res.stderr}`);
391
+ case "exhausted":
392
+ return done(false, `dev moved before each of ${res.attempts} pushes`);
393
+ case "fetch-failed":
394
+ return done(false, `fetch of dev failed: ${res.stderr}`);
395
+ case "setup-failed":
396
+ return done(false, `throwaway checkout failed: ${res.stderr}`);
404
397
  }
405
398
  }
406
399
  function writeBoard(md, board) {
@@ -478,7 +471,7 @@ export const roadmapCommand = {
478
471
  run: (ctx) => feature(ctx),
479
472
  },
480
473
  mirror: {
481
- summary: "Build / debug close: append the feature row in the worktree, then the same row on dev under the dev lock (fail-open).",
474
+ summary: "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).",
482
475
  flags: [
483
476
  { name: "workflow", type: "string", required: true, help: "build | debug" },
484
477
  { name: "fid", type: "string", required: true, help: "feature id (the row's key)" },
@@ -487,7 +480,7 @@ export const roadmapCommand = {
487
480
  row: "the row appended (worktree and dev)",
488
481
  appended: "false when the worktree ledger could not be written",
489
482
  mirrored: "the row was committed and pushed on dev",
490
- skipped: "why the dev side was skipped: adopt mode | dev lock busy | dev checkout / pull failed | dev push failed (null when mirrored)",
483
+ skipped: "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)",
491
484
  },
492
485
  run: (ctx) => mirror(ctx),
493
486
  },
@@ -81,8 +81,9 @@ export function classify(env, root, log) {
81
81
  }
82
82
  /**
83
83
  * Default capabilities per runtime. CLOUD_CURSOR matches GITHUB_ACTION on
84
- * purpose (isolated VM, real git, mints and pushes its own branch); a claude.ai
85
- * session's proxy only lets it push the current branch, so it gets neither.
84
+ * purpose (isolated VM, real git, mints and pushes its own branch). A claude.ai
85
+ * session gets neither: whether it may push dev can't be tested without making
86
+ * that push, and a wrong guess strands the session on a dev checkout.
86
87
  */
87
88
  const capable = (runtime) => runtime === "LOCAL" || runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR";
88
89
  /** No human can reply into the session: a GitHub Actions run. */
@@ -2,7 +2,7 @@
2
2
  import * as fs from "node:fs";
3
3
  import * as path from "node:path";
4
4
  import { activeDoneSteps, appendLine, fold, lastDoneStepAllRuns, lastRun, nextStrategy, runOrStepField, statusTimestamp, } from "../../ledgers/status.js";
5
- import { CommandError, EXIT, parseJson, statusLocation, } from "../lib.js";
5
+ import { CommandError, EXIT, git, parseJson, statusLocation, } from "../lib.js";
6
6
  // ---------------------------------------------------------------------------
7
7
  // Shared with counters / steps
8
8
  // ---------------------------------------------------------------------------
@@ -31,22 +31,46 @@ export const SUB_PLAN_FLAG = {
31
31
  };
32
32
  /** Exit code: status.jsonl missing, unreadable, or not valid NDJSON. */
33
33
  export const EXIT_NO_STATUS = 3;
34
- /** Parse every line of `status.jsonl`. Missing, unreadable or malformed is an error, never "no rows". */
35
34
  /** Every row of status.jsonl, whatever its type; exit 3 when the file is missing or a line is not JSON. */
36
35
  export function readStatusRows(file) {
37
36
  if (!fs.existsSync(file))
38
37
  throw new CommandError(EXIT_NO_STATUS, `${file} does not exist`);
39
- return fs
40
- .readFileSync(file, "utf-8")
38
+ return parseStatusRows(fs.readFileSync(file, "utf-8"), file);
39
+ }
40
+ /**
41
+ * The rows of status.jsonl as committed on `ref`, not as on disk: exit 3 when
42
+ * the ref does not carry the file. `file` need not exist; the repo is the one
43
+ * holding its nearest existing parent directory.
44
+ */
45
+ export function readStatusRowsAt(file, ref) {
46
+ let dir = path.dirname(file);
47
+ while (!fs.existsSync(dir) && path.dirname(dir) !== dir)
48
+ dir = path.dirname(dir);
49
+ const top = git(dir, ["rev-parse", "--show-toplevel"]);
50
+ if (top === null)
51
+ throw new CommandError(EXIT_NO_STATUS, `${file} is not inside a git repo`);
52
+ const rel = path
53
+ .relative(fs.realpathSync(top), path.join(fs.realpathSync(dir), path.relative(dir, file)))
54
+ .split(path.sep)
55
+ .join("/");
56
+ const spec = `${ref}:${rel}`;
57
+ const text = git(top, ["show", spec]);
58
+ if (text === null)
59
+ throw new CommandError(EXIT_NO_STATUS, `${spec} does not exist`);
60
+ return parseStatusRows(text, spec);
61
+ }
62
+ /** Parse NDJSON status text; `label` names it in errors. Malformed is an error, never "no rows". */
63
+ function parseStatusRows(text, label) {
64
+ return text
41
65
  .split("\n")
42
66
  .map((l) => l.trim())
43
67
  .filter((l) => l !== "")
44
68
  .map((l, i) => {
45
69
  const parsed = parseJson(l);
46
70
  if (!parsed.ok)
47
- throw new CommandError(EXIT_NO_STATUS, `${file} line ${i + 1} is not JSON`);
71
+ throw new CommandError(EXIT_NO_STATUS, `${label} line ${i + 1} is not JSON`);
48
72
  if (typeof parsed.value !== "object" || parsed.value === null) {
49
- throw new CommandError(EXIT_NO_STATUS, `${file} line ${i + 1} is not a JSON object`);
73
+ throw new CommandError(EXIT_NO_STATUS, `${label} line ${i + 1} is not a JSON object`);
50
74
  }
51
75
  return parsed.value;
52
76
  });
@@ -54,6 +78,8 @@ export function readStatusRows(file) {
54
78
  /** The rows as the fold reads them; the fold skips types it does not model. */
55
79
  export const readStatusEvents = (file) => readStatusRows(file);
56
80
  export const readRuns = (file) => fold(readStatusEvents(file));
81
+ /** The runs as committed on `ref` (see readStatusRowsAt). */
82
+ export const readRunsAt = (file, ref) => fold(readStatusRowsAt(file, ref));
57
83
  /** `--file`, resolved against the command's working directory. */
58
84
  export const statusFile = (ctx) => path.resolve(ctx.cwd, String(ctx.flags.file));
59
85
  /** `--field key=value`: value parsed as JSON when it parses, else kept as a string. */
@@ -197,11 +223,6 @@ export const statusCommand = {
197
223
  WORKFLOW_FLAG,
198
224
  { name: "fid", type: "string", required: true, help: "feature id" },
199
225
  { name: "month", type: "string", required: true, help: "month bucket, YYYYMM" },
200
- {
201
- name: "dev-pushes",
202
- type: "boolean",
203
- help: "ship only: this runtime pushes to dev (RUNTIME_DEVPUSHES=true)",
204
- },
205
226
  ],
206
227
  output: {
207
228
  path: "absolute path to status.jsonl",
@@ -217,7 +238,6 @@ export const statusCommand = {
217
238
  workflow: String(ctx.flags.workflow),
218
239
  fid: String(ctx.flags.fid),
219
240
  month,
220
- devPushes: ctx.flags.devPushes === true,
221
241
  });
222
242
  ctx.emit({ ...loc, exists: fs.existsSync(loc.path) });
223
243
  return EXIT.OK;
@@ -18,8 +18,8 @@ import { getPromptsRoot } from "../../shared/package-roots.js";
18
18
  import { CommandError, EXIT, repoRoot, runGit, } from "../lib.js";
19
19
  import { FID_PATTERNS, readIssueTracker } from "./fids.js";
20
20
  import { buildComment } from "./issues.js";
21
- import { lockRoot, readHolder, resolveMonth, workflowLockPath } from "./locks.js";
22
- import { EXIT_NO_STATUS, FILE_FLAG, STEP_FLAG, SUB_PLAN_FLAG, WORKFLOW_FLAG, extraField, nonNegativeInt, positiveInt, readRuns, statusFile, str, } from "./status.js";
21
+ import { readHolder, resolveMonth, workflowLockPath } from "./locks.js";
22
+ import { EXIT_NO_STATUS, FILE_FLAG, STEP_FLAG, SUB_PLAN_FLAG, WORKFLOW_FLAG, extraField, nonNegativeInt, positiveInt, readRuns, readRunsAt, statusFile, str, } from "./status.js";
23
23
  const VERDICT_END = "<!-- verdict:end -->";
24
24
  const DEFAULT_VERDICTS = ["PASS", "CONCERNS", "FAIL"];
25
25
  const STRATEGIES = ["STANDARD", "PIVOT", "FINAL"];
@@ -329,7 +329,8 @@ function gateChecks(cwd, o) {
329
329
  ? undefined
330
330
  : `does not match the ${tracker} shape ${FID_PATTERNS[tracker].source}`, `${tracker} shape`);
331
331
  if (o.token !== undefined) {
332
- const lock = workflowLockPath(lockRoot(cwd, o.workflow, o.devPushes === true), resolveMonth(repoRoot(cwd), o.fid, o.month), o.fid);
332
+ const root = repoRoot(cwd);
333
+ const lock = workflowLockPath(root, resolveMonth(root, o.fid, o.month), o.fid);
333
334
  const holder = readHolder(lock);
334
335
  add("workflow lock", holder === undefined
335
336
  ? `no lock at ${lock}`
@@ -365,7 +366,8 @@ function gateChecks(cwd, o) {
365
366
  }
366
367
  if (o.file === undefined)
367
368
  return checks;
368
- const rows = activeDoneSteps(readRuns(o.file), o.workflow, { step: o.step, subPlan: o.subPlan });
369
+ const runs = o.ref === undefined ? readRuns(o.file) : readRunsAt(o.file, o.ref);
370
+ const rows = activeDoneSteps(runs, o.workflow, { step: o.step, subPlan: o.subPlan });
369
371
  const row = rows.filter((r) => o.attempt === undefined || r.attempt === o.attempt).at(-1);
370
372
  const rowProblems = [];
371
373
  if (!row) {
@@ -981,6 +983,11 @@ export const stepsCommand = {
981
983
  required: false,
982
984
  help: "path to status.jsonl; without it the status row is not checked (Step 1)",
983
985
  },
986
+ {
987
+ name: "ref",
988
+ type: "string",
989
+ help: "read --file as committed on this ref (e.g. origin/dev), not from disk",
990
+ },
984
991
  WORKFLOW_FLAG,
985
992
  STEP_FLAG,
986
993
  SUB_PLAN_FLAG,
@@ -1019,15 +1026,10 @@ export const stepsCommand = {
1019
1026
  type: "string",
1020
1027
  help: "the workflow lock must be held with this token (needs --fid)",
1021
1028
  },
1022
- {
1023
- name: "dev-pushes",
1024
- type: "boolean",
1025
- help: "ship only: the lock lives in the main checkout",
1026
- },
1027
1029
  ],
1028
1030
  output: { pass: "true when every check passed", checks: "[{check, ok, detail}] per check" },
1029
1031
  exitCodes: {
1030
- [EXIT_NO_STATUS]: "status.jsonl missing, unreadable, or not valid NDJSON",
1032
+ [EXIT_NO_STATUS]: "status.jsonl missing (on disk, or on --ref), unreadable, or not valid NDJSON",
1031
1033
  },
1032
1034
  run: (ctx) => {
1033
1035
  const f = ctx.flags;
@@ -1038,11 +1040,17 @@ export const stepsCommand = {
1038
1040
  throw new CommandError(EXIT.USAGE, "give --attempt or --attempt-of, not both");
1039
1041
  if (f.attemptOf !== undefined && file === undefined)
1040
1042
  throw new CommandError(EXIT.USAGE, "--attempt-of needs --file");
1043
+ const ref = str(f.ref);
1044
+ if (ref !== undefined && file === undefined)
1045
+ throw new CommandError(EXIT.USAGE, "--ref needs --file");
1046
+ if (ref !== undefined && f.attemptOf !== undefined)
1047
+ throw new CommandError(EXIT.USAGE, "--attempt-of reads the file on disk; give --attempt with --ref");
1041
1048
  const attempt = f.attemptOf !== undefined
1042
1049
  ? derivedCounter(file, workflow, String(f.attemptOf), subPlan, undefined)
1043
1050
  : nonNegativeInt(f.attempt, "attempt");
1044
1051
  const checks = gateChecks(ctx.cwd, {
1045
1052
  file,
1053
+ ref,
1046
1054
  workflow,
1047
1055
  step: String(f.step),
1048
1056
  subPlan,
@@ -1053,7 +1061,6 @@ export const stepsCommand = {
1053
1061
  fid: str(f.fid),
1054
1062
  month: str(f.month),
1055
1063
  token: str(f.token),
1056
- devPushes: f.devPushes === true,
1057
1064
  placeholders: list(f.placeholder),
1058
1065
  });
1059
1066
  const pass = checks.every((c) => c.ok);