@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
@@ -48,10 +48,17 @@ export function cutEarlier(text) {
48
48
  }
49
49
  /**
50
50
  * Comments as an MCP read returns them: a bare array, or one wrapped under
51
- * `comments` / `nodes`; each a string or an object with `body` and an optional
52
- * `created_at` (GitHub) / `createdAt` (Linear).
51
+ * `comments` / `nodes` (Jira's adds a `data` envelope); each a string or an object
52
+ * with `body` and an optional `created_at` (GitHub) / `createdAt` (Linear) /
53
+ * `created` (Jira).
53
54
  */
54
55
  export function parseComments(raw) {
56
+ const outer = raw;
57
+ const inner = outer !== null && typeof outer === "object" && !Array.isArray(outer) && "data" in outer
58
+ ? outer.data
59
+ : raw;
60
+ if (inner !== raw)
61
+ return parseComments(inner);
55
62
  const wrapped = raw;
56
63
  const list = Array.isArray(raw)
57
64
  ? raw
@@ -71,7 +78,7 @@ export function parseComments(raw) {
71
78
  const obj = (item ?? {});
72
79
  if (typeof obj.body !== "string")
73
80
  return null;
74
- const at = obj.created_at ?? obj.createdAt;
81
+ const at = obj.created_at ?? obj.createdAt ?? obj.created;
75
82
  out.push({ body: obj.body, createdAt: typeof at === "string" ? at : undefined });
76
83
  }
77
84
  return out;
@@ -125,7 +132,16 @@ function textVerb(ctx) {
125
132
  // labels
126
133
  // ---------------------------------------------------------------------------
127
134
  /** Mutually exclusive: setting one drops the others. */
128
- export const PHASE_LABELS = ["bkit:design", "bkit:plan", "bkit:build", "bkit:ship", "bkit:merged"];
135
+ export const PHASE_LABELS = [
136
+ "bkit:design",
137
+ "bkit:plan",
138
+ "bkit:build",
139
+ "bkit:debug",
140
+ "bkit:ship",
141
+ "bkit:merged",
142
+ ];
143
+ /** Prefix of the labels naming an issue's next best workflow; setting a phase drops them. */
144
+ export const NEXT_LABEL_PREFIX = "next:";
129
145
  /** The issue label that opts a feature into CI auto-routing. */
130
146
  export const AUTO_LABEL = "bkit:auto";
131
147
  /** Commit-subject suffix the CI auto-route gate matches; carried only while the issue has `AUTO_LABEL`. */
@@ -145,12 +161,15 @@ export function transitionLabels(current, t) {
145
161
  for (const l of have)
146
162
  if (PHASE_LABELS.includes(l) && l !== label)
147
163
  remove.add(l);
164
+ for (const l of have)
165
+ if (l.startsWith(NEXT_LABEL_PREFIX))
166
+ remove.add(l);
148
167
  want(label, true);
149
168
  }
150
- if (t.failed !== undefined)
151
- want("bkit:failed", t.failed);
152
- if (t.debug !== undefined)
153
- want("bkit:debug", t.debug);
169
+ // A phase starting supersedes any earlier Failure Path.
170
+ const failed = t.failed ?? (t.phase !== undefined ? false : undefined);
171
+ if (failed !== undefined)
172
+ want("bkit:failed", failed);
154
173
  return {
155
174
  add,
156
175
  remove: [...remove],
@@ -158,19 +177,25 @@ export function transitionLabels(current, t) {
158
177
  };
159
178
  }
160
179
  /**
161
- * Linear's issue state for the same transition, as the workflows set it: a
162
- * shipped, failed or debugged issue waits on a human ("In Review"); a phase
163
- * starting is "In Progress". Null when the transition sets no state.
180
+ * The issue state the workflows set for the same transition, on a tracker whose
181
+ * board status is the issue state: `bkit.linear` or `bkit.jira`. A shipped
182
+ * or failed issue waits on a human (`review`); a phase starting is `progress`.
183
+ * The workflows write it alone, so a name the team or project lacks leaves the
184
+ * labels landed. Null under github (the Projects v2 board moves instead) and
185
+ * none, or when the transition sets no state.
164
186
  */
165
- export function linearState(t, board) {
166
- if (t.phase === "merged" || t.failed === true || t.debug === true)
167
- return "In Review";
187
+ export function trackerState(t, board, cfg) {
188
+ const states = cfg.issueTracker === "linear" ? cfg.linear : cfg.issueTracker === "jira" ? cfg.jira : null;
189
+ if (states === null)
190
+ return null;
191
+ if (t.phase === "merged" || t.failed === true)
192
+ return states.review;
168
193
  if (t.phase !== undefined)
169
- return "In Progress";
194
+ return states.progress;
170
195
  if (board === "review")
171
- return "In Review";
196
+ return states.review;
172
197
  if (board === "progress")
173
- return "In Progress";
198
+ return states.progress;
174
199
  return null;
175
200
  }
176
201
  const ON_OFF = { on: true, off: false };
@@ -196,7 +221,7 @@ function boardPayload(ctx, status) {
196
221
  const root = repoRoot(ctx.cwd);
197
222
  const tracker = readBkitConfig(root).issueTracker;
198
223
  if (tracker !== "github") {
199
- if (tracker === "linear")
224
+ if (tracker === "linear" || tracker === "jira")
200
225
  ctx.log("Board status carried by issue state — no separate update.");
201
226
  return { board: null, boardSkipped: `tracker-${tracker}` };
202
227
  }
@@ -253,21 +278,16 @@ function boardPayload(ctx, status) {
253
278
  function labelsVerb(ctx) {
254
279
  const phase = str(ctx.flags.phase);
255
280
  if (phase !== undefined && !PHASE_LABELS.includes(`bkit:${phase}`)) {
256
- throw new CommandError(EXIT.USAGE, "--phase must be design, plan, build, ship, or merged");
257
- }
258
- let failed = onOff(ctx.flags.failed, "failed");
259
- const debug = onOff(ctx.flags.debug, "debug");
260
- // A merged issue must not keep a stale Failure Path marker.
261
- if (phase === "merged") {
262
- if (failed === true)
263
- throw new CommandError(EXIT.USAGE, "--phase=merged clears bkit:failed; drop --failed=on");
264
- failed = false;
281
+ throw new CommandError(EXIT.USAGE, "--phase must be design, plan, build, debug, ship, or merged");
265
282
  }
283
+ const failed = onOff(ctx.flags.failed, "failed");
284
+ if (phase !== undefined && failed === true)
285
+ throw new CommandError(EXIT.USAGE, "--phase clears bkit:failed; drop --failed=on");
266
286
  const board = str(ctx.flags.board);
267
287
  if (board !== undefined && BOARD_OPTION[board] === undefined) {
268
288
  throw new CommandError(EXIT.USAGE, "--board must be progress or review");
269
289
  }
270
- const t = { phase, failed, debug };
290
+ const t = { phase, failed };
271
291
  const { add, remove, labels } = transitionLabels(ctx.flags.label ?? [], t);
272
292
  const { board: payload, boardSkipped } = board === undefined ? { board: null, boardSkipped: null } : boardPayload(ctx, board);
273
293
  ctx.emit({
@@ -276,7 +296,7 @@ function labelsVerb(ctx) {
276
296
  labels,
277
297
  changed: add.length + remove.length > 0,
278
298
  autoRouteSuffix: labels.includes(AUTO_LABEL) ? AUTO_ROUTE_SUFFIX : "",
279
- linearState: linearState(t, board),
299
+ trackerState: trackerState(t, board, readBkitConfig(repoRoot(ctx.cwd))),
280
300
  board: payload,
281
301
  boardSkipped,
282
302
  });
@@ -360,12 +380,33 @@ function links(o) {
360
380
  const ref = o.ref ?? o.tree;
361
381
  if (ref === undefined)
362
382
  throw new CommandError(EXIT.USAGE, "--artifact needs --ref (or --tree)");
363
- for (const a of artifacts)
364
- out.push(`[${path.basename(a)}](${gh}/blob/${ref}/${a.replace(/^\/+/, "")})`);
383
+ for (const a of artifacts) {
384
+ const hash = a.indexOf("#");
385
+ const file = (hash < 0 ? a : a.slice(0, hash)).replace(/^\/+/, "");
386
+ const heading = hash < 0 ? undefined : a.slice(hash + 1).trim();
387
+ if (heading === "")
388
+ throw new CommandError(EXIT.USAGE, `--artifact "${a}" has an empty #Heading`);
389
+ const url = `${gh}/blob/${ref}/${file}`;
390
+ out.push(heading === undefined
391
+ ? `[${path.basename(file)}](${url})`
392
+ : `[${path.basename(file)} § ${heading}](${url}#${headingAnchor(heading)})`);
393
+ }
365
394
  }
366
395
  return out;
367
396
  }
368
- const KINDS = ["step", "failure", "handover"];
397
+ /**
398
+ * GitHub's anchor for a markdown heading: lowercased, punctuation dropped,
399
+ * spaces to hyphens. A repeated heading's later copies take `-1`, `-2`; this
400
+ * names the first.
401
+ */
402
+ export function headingAnchor(heading) {
403
+ return heading
404
+ .trim()
405
+ .toLowerCase()
406
+ .replace(/[^\p{L}\p{M}\p{N}\p{Pc} -]/gu, "")
407
+ .replace(/ /g, "-");
408
+ }
409
+ const KINDS = ["step", "failure", "handover", "audit"];
369
410
  /** The exact comment body; files (`bodyFile`, `sections`, `stderrFile`, `errorFile`) resolve against `cwd`. */
370
411
  export function buildComment(cwd, o) {
371
412
  const kind = o.kind ?? "step";
@@ -406,6 +447,13 @@ export function buildComment(cwd, o) {
406
447
  lines.push("Stderr:", fenced(captured));
407
448
  }
408
449
  }
450
+ else if (kind === "audit") {
451
+ const slug = o.auditSlug;
452
+ if (slug === undefined || !/^[a-z0-9-]+$/.test(slug)) {
453
+ throw new CommandError(EXIT.USAGE, "--kind=audit needs --audit-slug=<template slug>");
454
+ }
455
+ lines.push([`### Audit Summary: ${slug}`, ...(o.fields ?? []).map(([k, v]) => `${k}: ${v}`)].join(" - "));
456
+ }
409
457
  else {
410
458
  lines.push("### Workflow Handover");
411
459
  }
@@ -436,11 +484,12 @@ export function commentBody(ctx) {
436
484
  }
437
485
  return buildComment(ctx.cwd, {
438
486
  kind: kind,
487
+ auditSlug: str(ctx.flags.auditSlug),
439
488
  workflow: str(ctx.flags.workflow),
440
489
  workflowHeading: ctx.flags.workflowHeading === true,
441
490
  stepNumber: str(ctx.flags.stepNumber),
442
491
  stepTitle: str(ctx.flags.stepTitle),
443
- fields: kind === "step" ? headerFields(ctx) : [],
492
+ fields: kind === "step" || kind === "audit" ? headerFields(ctx) : [],
444
493
  subStep: str(ctx.flags.subStep),
445
494
  error: str(ctx.flags.error),
446
495
  errorFile: str(ctx.flags.errorFile),
@@ -484,16 +533,15 @@ export const issuesCommand = {
484
533
  run: textVerb,
485
534
  },
486
535
  labels: {
487
- summary: "Label arithmetic for a transition, the Linear state, and the board payload.",
536
+ summary: "Label arithmetic for a transition, the tracker state, and the board payload.",
488
537
  flags: [
489
538
  { name: "label", type: "string", repeatable: true, help: "a label the issue carries now" },
490
539
  {
491
540
  name: "phase",
492
541
  type: "string",
493
- help: "set this phase: design | plan | build | ship | merged",
542
+ help: "set this phase: design | plan | build | debug | ship | merged (drops next:* and bkit:failed)",
494
543
  },
495
- { name: "failed", type: "string", help: "bkit:failed on | off (merged implies off)" },
496
- { name: "debug", type: "string", help: "bkit:debug on | off" },
544
+ { name: "failed", type: "string", help: "bkit:failed on | off (a phase implies off)" },
497
545
  {
498
546
  name: "board",
499
547
  type: "string",
@@ -508,16 +556,17 @@ export const issuesCommand = {
508
556
  labels: "the full label set to write",
509
557
  changed: "whether add or remove is non-empty",
510
558
  autoRouteSuffix: `"${AUTO_ROUTE_SUFFIX}" when the label set carries ${AUTO_LABEL}, else ""`,
511
- linearState: "Linear issue state for this transition, or null",
559
+ trackerState: "Linear or Jira issue state for this transition, from package.json; null under github, none, or no state move",
512
560
  board: "projects payloads {addItem, listItems, updateItem}, or null",
513
561
  boardSkipped: "why board is null with --board: opted-out | not-configured | tracker-<name> | …",
514
562
  },
515
563
  run: labelsVerb,
516
564
  },
517
565
  comment: {
518
- summary: "The exact body of a ###### bkit:generated step, failure, or handover comment.",
566
+ summary: "The exact body of a ###### bkit:generated step, failure, handover, or audit comment.",
519
567
  flags: [
520
- { name: "kind", type: "string", help: "step (default) | failure | handover" },
568
+ { name: "kind", type: "string", help: "step (default) | failure | handover | audit" },
569
+ { name: "audit-slug", type: "string", help: "audit: template slug, e.g. security" },
521
570
  { name: "step-number", type: "string", help: "step number in the heading" },
522
571
  { name: "step-title", type: "string", help: "step title in the heading, e.g. Plan Verify" },
523
572
  { name: "workflow", type: "string", help: "design | plan | build | debug | ship | auto" },
@@ -548,7 +597,7 @@ export const issuesCommand = {
548
597
  name: "artifact",
549
598
  type: "string",
550
599
  repeatable: true,
551
- help: "link this repo path at --ref",
600
+ help: "link this repo path at --ref; path#Heading links that section",
552
601
  },
553
602
  { name: "ref", type: "string", help: "ref the --artifact links point at (default --tree)" },
554
603
  { name: "line", type: "string", repeatable: true, help: "a raw line after the links" },
@@ -425,23 +425,38 @@ export function checkOnlyBookkeeping(root, o) {
425
425
  if (gitRaw(root, ["merge-base", "--is-ancestor", o.from, o.to]).status !== 0) {
426
426
  return { kind: "not-ancestor" };
427
427
  }
428
- const changed = (specs) => gitRaw(root, [
428
+ const diff = changedOutside(root, o.from, o.to, bookPathspecs(o.month, o.fid, "pr"));
429
+ if (!diff.ok)
430
+ return { kind: "diff-failed", stderr: diff.stderr };
431
+ return diff.outside.length ? { kind: "outside", outside: diff.outside } : { kind: "ok" };
432
+ }
433
+ /**
434
+ * Every path changed in `from..to`, and the ones no pathspec in `specs` matches, both
435
+ * sorted. Git does the matching, so `specs` take pathspec magic (`:(glob)`). Renames
436
+ * count as a delete plus an add, so both paths must match.
437
+ */
438
+ export function changedOutside(root, from, to, specs) {
439
+ const diff = (only) => gitRaw(root, [
429
440
  "diff",
430
441
  "--name-only",
431
442
  "-z",
432
443
  "--no-renames",
433
- o.from,
434
- o.to,
435
- ...(specs.length ? ["--", ...specs] : []),
444
+ from,
445
+ to,
446
+ ...(only.length ? ["--", ...only] : []),
436
447
  ]);
437
- const all = changed([]);
438
- const book = changed(bookPathspecs(o.month, o.fid, "pr"));
439
- if (all.status !== 0 || book.status !== 0) {
440
- return { kind: "diff-failed", stderr: all.status !== 0 ? all.stderr : book.stderr };
441
- }
448
+ const all = diff([]);
449
+ if (all.status !== 0)
450
+ return { ok: false, stderr: all.stderr };
451
+ const changed = [...new Set(nulList(all.stdout))].sort();
452
+ // No specs = nothing allowed: `git diff` with no pathspec would match every path.
453
+ if (specs.length === 0)
454
+ return { ok: true, changed, outside: changed };
455
+ const book = diff(specs);
456
+ if (book.status !== 0)
457
+ return { ok: false, stderr: book.stderr };
442
458
  const allowed = new Set(nulList(book.stdout));
443
- const outside = [...new Set(nulList(all.stdout).filter((p) => !allowed.has(p)))].sort();
444
- return outside.length ? { kind: "outside", outside } : { kind: "ok" };
459
+ return { ok: true, changed, outside: changed.filter((p) => !allowed.has(p)) };
445
460
  }
446
461
  function onlyBookkeeping(ctx) {
447
462
  const month = required(ctx, "month");
@@ -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) {
@@ -115,11 +115,13 @@ function refFlag(value, flag) {
115
115
  const FID_FORMAT = {
116
116
  github: /^[0-9]+-[a-z0-9-]+$/,
117
117
  linear: /^[a-z]+-[0-9]+-[a-z0-9-]+$/,
118
+ jira: /^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$/,
118
119
  none: /^[a-z0-9][a-z0-9-]*$/,
119
120
  };
120
121
  const ISSUE_FORMAT = {
121
122
  github: /^[0-9]+$/,
122
123
  linear: /^[A-Z]+-[0-9]+$/,
124
+ jira: /^[A-Z][A-Z0-9]+-[0-9]+$/,
123
125
  };
124
126
  /** The PR-body marker line for this tracker (`.bkit/trackers.md` `pr-body-marker`). */
125
127
  export function prMarker(tracker, fid, issue) {
@@ -450,15 +452,18 @@ const TRANSPORTS = ["git", "gh", "mcp"];
450
452
  * a `git` close needs no `gh`, so a laptop that never ran `gh auth login` closes fine.
451
453
  */
452
454
  export function crossCheckFile(file, transport, log) {
455
+ return crossCheckRows(readStatusRows(file), file, transport, log);
456
+ }
457
+ /** crossCheckFile over rows already read; `label` names where they came from. */
458
+ export function crossCheckRows(rows, label, transport, log) {
453
459
  if (!TRANSPORTS.includes(transport)) {
454
460
  throw new CommandError(EXIT.USAGE, `--transport must be ${TRANSPORTS.join(", ")}`);
455
461
  }
456
- const rows = readStatusRows(file);
457
462
  const runtimeGithubCli = capability(lastRow(rows, "runtime-resolved")?.runtimeGithubCli);
458
463
  const fallbackRows = rows.filter((r) => r.type === "transport-fallback").length;
459
464
  const violated = runtimeGithubCli === false && transport === "mcp" && fallbackRows === 0;
460
465
  if (violated) {
461
- log(`runtime-resolved logged runtimeGithubCli=false and this close used transport mcp, but no transport-fallback row exists in ${file}`);
466
+ log(`runtime-resolved logged runtimeGithubCli=false and this close used transport mcp, but no transport-fallback row exists in ${label}`);
462
467
  }
463
468
  return { ok: !violated, runtimeGithubCli, transport, fallbackRows };
464
469
  }
@@ -594,7 +599,7 @@ export const prsCommand = {
594
599
  {
595
600
  name: "issue",
596
601
  type: "string",
597
- help: "issue id for the marker (github: 123 or #123; linear: ABC-123)",
602
+ help: "issue id for the marker (github: 123 or #123; linear / jira: ABC-123)",
598
603
  },
599
604
  BASE_FLAG,
600
605
  HEAD_FLAG,