@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
@@ -17,7 +17,7 @@ import {
17
17
  type CommandSpec,
18
18
  type RunContext,
19
19
  } from "../lib.js";
20
- import { readBkitConfig } from "../../shared/settings.js";
20
+ import { readBkitConfig, type BkitConfig } from "../../shared/settings.js";
21
21
  import { str } from "./status.js";
22
22
 
23
23
  /** Exit code: an input file is missing or not in the expected shape. */
@@ -68,10 +68,17 @@ export function cutEarlier(text: string): { text: string; cut: boolean } {
68
68
 
69
69
  /**
70
70
  * Comments as an MCP read returns them: a bare array, or one wrapped under
71
- * `comments` / `nodes`; each a string or an object with `body` and an optional
72
- * `created_at` (GitHub) / `createdAt` (Linear).
71
+ * `comments` / `nodes` (Jira's adds a `data` envelope); each a string or an object
72
+ * with `body` and an optional `created_at` (GitHub) / `createdAt` (Linear) /
73
+ * `created` (Jira).
73
74
  */
74
75
  export function parseComments(raw: unknown): IssueComment[] | null {
76
+ const outer = raw as { data?: unknown } | null;
77
+ const inner =
78
+ outer !== null && typeof outer === "object" && !Array.isArray(outer) && "data" in outer
79
+ ? outer.data
80
+ : raw;
81
+ if (inner !== raw) return parseComments(inner);
75
82
  const wrapped = raw as { comments?: unknown; nodes?: unknown } | null;
76
83
  const list = Array.isArray(raw)
77
84
  ? raw
@@ -89,7 +96,7 @@ export function parseComments(raw: unknown): IssueComment[] | null {
89
96
  }
90
97
  const obj = (item ?? {}) as Record<string, unknown>;
91
98
  if (typeof obj.body !== "string") return null;
92
- const at = obj.created_at ?? obj.createdAt;
99
+ const at = obj.created_at ?? obj.createdAt ?? obj.created;
93
100
  out.push({ body: obj.body, createdAt: typeof at === "string" ? at : undefined });
94
101
  }
95
102
  return out;
@@ -154,7 +161,17 @@ function textVerb(ctx: RunContext): number {
154
161
  // ---------------------------------------------------------------------------
155
162
 
156
163
  /** Mutually exclusive: setting one drops the others. */
157
- export const PHASE_LABELS = ["bkit:design", "bkit:plan", "bkit:build", "bkit:ship", "bkit:merged"];
164
+ export const PHASE_LABELS = [
165
+ "bkit:design",
166
+ "bkit:plan",
167
+ "bkit:build",
168
+ "bkit:debug",
169
+ "bkit:ship",
170
+ "bkit:merged",
171
+ ];
172
+
173
+ /** Prefix of the labels naming an issue's next best workflow; setting a phase drops them. */
174
+ export const NEXT_LABEL_PREFIX = "next:";
158
175
 
159
176
  /** The issue label that opts a feature into CI auto-routing. */
160
177
  export const AUTO_LABEL = "bkit:auto";
@@ -164,7 +181,6 @@ export const AUTO_ROUTE_SUFFIX = " bkit [auto route]";
164
181
  export interface LabelTransition {
165
182
  phase?: string;
166
183
  failed?: boolean;
167
- debug?: boolean;
168
184
  }
169
185
 
170
186
  export function transitionLabels(current: string[], t: LabelTransition) {
@@ -178,10 +194,12 @@ export function transitionLabels(current: string[], t: LabelTransition) {
178
194
  if (t.phase !== undefined) {
179
195
  const label = `bkit:${t.phase}`;
180
196
  for (const l of have) if (PHASE_LABELS.includes(l) && l !== label) remove.add(l);
197
+ for (const l of have) if (l.startsWith(NEXT_LABEL_PREFIX)) remove.add(l);
181
198
  want(label, true);
182
199
  }
183
- if (t.failed !== undefined) want("bkit:failed", t.failed);
184
- if (t.debug !== undefined) want("bkit:debug", t.debug);
200
+ // A phase starting supersedes any earlier Failure Path.
201
+ const failed = t.failed ?? (t.phase !== undefined ? false : undefined);
202
+ if (failed !== undefined) want("bkit:failed", failed);
185
203
  return {
186
204
  add,
187
205
  remove: [...remove],
@@ -190,15 +208,25 @@ export function transitionLabels(current: string[], t: LabelTransition) {
190
208
  }
191
209
 
192
210
  /**
193
- * Linear's issue state for the same transition, as the workflows set it: a
194
- * shipped, failed or debugged issue waits on a human ("In Review"); a phase
195
- * starting is "In Progress". Null when the transition sets no state.
211
+ * The issue state the workflows set for the same transition, on a tracker whose
212
+ * board status is the issue state: `bkit.linear` or `bkit.jira`. A shipped
213
+ * or failed issue waits on a human (`review`); a phase starting is `progress`.
214
+ * The workflows write it alone, so a name the team or project lacks leaves the
215
+ * labels landed. Null under github (the Projects v2 board moves instead) and
216
+ * none, or when the transition sets no state.
196
217
  */
197
- export function linearState(t: LabelTransition, board: string | undefined): string | null {
198
- if (t.phase === "merged" || t.failed === true || t.debug === true) return "In Review";
199
- if (t.phase !== undefined) return "In Progress";
200
- if (board === "review") return "In Review";
201
- if (board === "progress") return "In Progress";
218
+ export function trackerState(
219
+ t: LabelTransition,
220
+ board: string | undefined,
221
+ cfg: Pick<BkitConfig, "issueTracker" | "linear" | "jira">,
222
+ ): string | null {
223
+ const states =
224
+ cfg.issueTracker === "linear" ? cfg.linear : cfg.issueTracker === "jira" ? cfg.jira : null;
225
+ if (states === null) return null;
226
+ if (t.phase === "merged" || t.failed === true) return states.review;
227
+ if (t.phase !== undefined) return states.progress;
228
+ if (board === "review") return states.review;
229
+ if (board === "progress") return states.progress;
202
230
  return null;
203
231
  }
204
232
 
@@ -229,7 +257,8 @@ function boardPayload(
229
257
  const root = repoRoot(ctx.cwd);
230
258
  const tracker = readBkitConfig(root).issueTracker;
231
259
  if (tracker !== "github") {
232
- if (tracker === "linear") ctx.log("Board status carried by issue state — no separate update.");
260
+ if (tracker === "linear" || tracker === "jira")
261
+ ctx.log("Board status carried by issue state — no separate update.");
233
262
  return { board: null, boardSkipped: `tracker-${tracker}` };
234
263
  }
235
264
  const gp = readBkitConfig(root).githubProject;
@@ -288,21 +317,19 @@ function boardPayload(
288
317
  function labelsVerb(ctx: RunContext): number {
289
318
  const phase = str(ctx.flags.phase);
290
319
  if (phase !== undefined && !PHASE_LABELS.includes(`bkit:${phase}`)) {
291
- throw new CommandError(EXIT.USAGE, "--phase must be design, plan, build, ship, or merged");
292
- }
293
- let failed = onOff(ctx.flags.failed, "failed");
294
- const debug = onOff(ctx.flags.debug, "debug");
295
- // A merged issue must not keep a stale Failure Path marker.
296
- if (phase === "merged") {
297
- if (failed === true)
298
- throw new CommandError(EXIT.USAGE, "--phase=merged clears bkit:failed; drop --failed=on");
299
- failed = false;
320
+ throw new CommandError(
321
+ EXIT.USAGE,
322
+ "--phase must be design, plan, build, debug, ship, or merged",
323
+ );
300
324
  }
325
+ const failed = onOff(ctx.flags.failed, "failed");
326
+ if (phase !== undefined && failed === true)
327
+ throw new CommandError(EXIT.USAGE, "--phase clears bkit:failed; drop --failed=on");
301
328
  const board = str(ctx.flags.board);
302
329
  if (board !== undefined && BOARD_OPTION[board] === undefined) {
303
330
  throw new CommandError(EXIT.USAGE, "--board must be progress or review");
304
331
  }
305
- const t: LabelTransition = { phase, failed, debug };
332
+ const t: LabelTransition = { phase, failed };
306
333
  const { add, remove, labels } = transitionLabels(
307
334
  (ctx.flags.label as string[] | undefined) ?? [],
308
335
  t,
@@ -315,7 +342,7 @@ function labelsVerb(ctx: RunContext): number {
315
342
  labels,
316
343
  changed: add.length + remove.length > 0,
317
344
  autoRouteSuffix: labels.includes(AUTO_LABEL) ? AUTO_ROUTE_SUFFIX : "",
318
- linearState: linearState(t, board),
345
+ trackerState: trackerState(t, board, readBkitConfig(repoRoot(ctx.cwd))),
319
346
  board: payload,
320
347
  boardSkipped,
321
348
  });
@@ -383,7 +410,9 @@ function fenced(text: string): string {
383
410
 
384
411
  /** Everything one `###### bkit:generated` comment is built from. */
385
412
  export interface CommentInput {
386
- kind?: "step" | "failure" | "handover";
413
+ kind?: "step" | "failure" | "handover" | "audit";
414
+ /** Audit: the template slug in `### Audit Summary: <slug>`. */
415
+ auditSlug?: string;
387
416
  /** With `workflowHeading`: Step 1 puts `## <Workflow>` above the step. */
388
417
  workflow?: string;
389
418
  workflowHeading?: boolean;
@@ -401,7 +430,7 @@ export interface CommentInput {
401
430
  prNumber?: string;
402
431
  prUrl?: string;
403
432
  runId?: string;
404
- /** Repo paths linked at `ref` (default `tree`). */
433
+ /** Repo paths linked at `ref` (default `tree`); `path#Heading` links that section. */
405
434
  artifacts?: string[];
406
435
  ref?: string;
407
436
  lines?: string[];
@@ -429,13 +458,37 @@ function links(o: CommentInput): string[] {
429
458
  if (artifacts.length) {
430
459
  const ref = o.ref ?? o.tree;
431
460
  if (ref === undefined) throw new CommandError(EXIT.USAGE, "--artifact needs --ref (or --tree)");
432
- for (const a of artifacts)
433
- out.push(`[${path.basename(a)}](${gh}/blob/${ref}/${a.replace(/^\/+/, "")})`);
461
+ for (const a of artifacts) {
462
+ const hash = a.indexOf("#");
463
+ const file = (hash < 0 ? a : a.slice(0, hash)).replace(/^\/+/, "");
464
+ const heading = hash < 0 ? undefined : a.slice(hash + 1).trim();
465
+ if (heading === "")
466
+ throw new CommandError(EXIT.USAGE, `--artifact "${a}" has an empty #Heading`);
467
+ const url = `${gh}/blob/${ref}/${file}`;
468
+ out.push(
469
+ heading === undefined
470
+ ? `[${path.basename(file)}](${url})`
471
+ : `[${path.basename(file)} § ${heading}](${url}#${headingAnchor(heading)})`,
472
+ );
473
+ }
434
474
  }
435
475
  return out;
436
476
  }
437
477
 
438
- const KINDS = ["step", "failure", "handover"];
478
+ /**
479
+ * GitHub's anchor for a markdown heading: lowercased, punctuation dropped,
480
+ * spaces to hyphens. A repeated heading's later copies take `-1`, `-2`; this
481
+ * names the first.
482
+ */
483
+ export function headingAnchor(heading: string): string {
484
+ return heading
485
+ .trim()
486
+ .toLowerCase()
487
+ .replace(/[^\p{L}\p{M}\p{N}\p{Pc} -]/gu, "")
488
+ .replace(/ /g, "-");
489
+ }
490
+
491
+ const KINDS = ["step", "failure", "handover", "audit"];
439
492
 
440
493
  /** The exact comment body; files (`bodyFile`, `sections`, `stderrFile`, `errorFile`) resolve against `cwd`. */
441
494
  export function buildComment(cwd: string, o: CommentInput): string {
@@ -490,6 +543,14 @@ export function buildComment(cwd: string, o: CommentInput): string {
490
543
  const captured = tail(readInput(cwd, o.stderrFile, "stderr-file"), 20);
491
544
  if (captured.trim() !== "") lines.push("Stderr:", fenced(captured));
492
545
  }
546
+ } else if (kind === "audit") {
547
+ const slug = o.auditSlug;
548
+ if (slug === undefined || !/^[a-z0-9-]+$/.test(slug)) {
549
+ throw new CommandError(EXIT.USAGE, "--kind=audit needs --audit-slug=<template slug>");
550
+ }
551
+ lines.push(
552
+ [`### Audit Summary: ${slug}`, ...(o.fields ?? []).map(([k, v]) => `${k}: ${v}`)].join(" - "),
553
+ );
493
554
  } else {
494
555
  lines.push("### Workflow Handover");
495
556
  }
@@ -522,11 +583,12 @@ export function commentBody(ctx: RunContext): string {
522
583
  }
523
584
  return buildComment(ctx.cwd, {
524
585
  kind: kind as CommentInput["kind"],
586
+ auditSlug: str(ctx.flags.auditSlug),
525
587
  workflow: str(ctx.flags.workflow),
526
588
  workflowHeading: ctx.flags.workflowHeading === true,
527
589
  stepNumber: str(ctx.flags.stepNumber),
528
590
  stepTitle: str(ctx.flags.stepTitle),
529
- fields: kind === "step" ? headerFields(ctx) : [],
591
+ fields: kind === "step" || kind === "audit" ? headerFields(ctx) : [],
530
592
  subStep: str(ctx.flags.subStep),
531
593
  error: str(ctx.flags.error),
532
594
  errorFile: str(ctx.flags.errorFile),
@@ -572,16 +634,15 @@ export const issuesCommand: CommandSpec = {
572
634
  run: textVerb,
573
635
  },
574
636
  labels: {
575
- summary: "Label arithmetic for a transition, the Linear state, and the board payload.",
637
+ summary: "Label arithmetic for a transition, the tracker state, and the board payload.",
576
638
  flags: [
577
639
  { name: "label", type: "string", repeatable: true, help: "a label the issue carries now" },
578
640
  {
579
641
  name: "phase",
580
642
  type: "string",
581
- help: "set this phase: design | plan | build | ship | merged",
643
+ help: "set this phase: design | plan | build | debug | ship | merged (drops next:* and bkit:failed)",
582
644
  },
583
- { name: "failed", type: "string", help: "bkit:failed on | off (merged implies off)" },
584
- { name: "debug", type: "string", help: "bkit:debug on | off" },
645
+ { name: "failed", type: "string", help: "bkit:failed on | off (a phase implies off)" },
585
646
  {
586
647
  name: "board",
587
648
  type: "string",
@@ -596,7 +657,8 @@ export const issuesCommand: CommandSpec = {
596
657
  labels: "the full label set to write",
597
658
  changed: "whether add or remove is non-empty",
598
659
  autoRouteSuffix: `"${AUTO_ROUTE_SUFFIX}" when the label set carries ${AUTO_LABEL}, else ""`,
599
- linearState: "Linear issue state for this transition, or null",
660
+ trackerState:
661
+ "Linear or Jira issue state for this transition, from package.json; null under github, none, or no state move",
600
662
  board: "projects payloads {addItem, listItems, updateItem}, or null",
601
663
  boardSkipped:
602
664
  "why board is null with --board: opted-out | not-configured | tracker-<name> | …",
@@ -604,9 +666,11 @@ export const issuesCommand: CommandSpec = {
604
666
  run: labelsVerb,
605
667
  },
606
668
  comment: {
607
- summary: "The exact body of a ###### bkit:generated step, failure, or handover comment.",
669
+ summary:
670
+ "The exact body of a ###### bkit:generated step, failure, handover, or audit comment.",
608
671
  flags: [
609
- { name: "kind", type: "string", help: "step (default) | failure | handover" },
672
+ { name: "kind", type: "string", help: "step (default) | failure | handover | audit" },
673
+ { name: "audit-slug", type: "string", help: "audit: template slug, e.g. security" },
610
674
  { name: "step-number", type: "string", help: "step number in the heading" },
611
675
  { name: "step-title", type: "string", help: "step title in the heading, e.g. Plan Verify" },
612
676
  { name: "workflow", type: "string", help: "design | plan | build | debug | ship | auto" },
@@ -637,7 +701,7 @@ export const issuesCommand: CommandSpec = {
637
701
  name: "artifact",
638
702
  type: "string",
639
703
  repeatable: true,
640
- help: "link this repo path at --ref",
704
+ help: "link this repo path at --ref; path#Heading links that section",
641
705
  },
642
706
  { name: "ref", type: "string", help: "ref the --artifact links point at (default --tree)" },
643
707
  { name: "line", type: "string", repeatable: true, help: "a raw line after the links" },
@@ -527,24 +527,41 @@ export function checkOnlyBookkeeping(
527
527
  if (gitRaw(root, ["merge-base", "--is-ancestor", o.from, o.to]).status !== 0) {
528
528
  return { kind: "not-ancestor" };
529
529
  }
530
- const changed = (specs: string[]) =>
530
+ const diff = changedOutside(root, o.from, o.to, bookPathspecs(o.month, o.fid, "pr"));
531
+ if (!diff.ok) return { kind: "diff-failed", stderr: diff.stderr };
532
+ return diff.outside.length ? { kind: "outside", outside: diff.outside } : { kind: "ok" };
533
+ }
534
+
535
+ /**
536
+ * Every path changed in `from..to`, and the ones no pathspec in `specs` matches, both
537
+ * sorted. Git does the matching, so `specs` take pathspec magic (`:(glob)`). Renames
538
+ * count as a delete plus an add, so both paths must match.
539
+ */
540
+ export function changedOutside(
541
+ root: string,
542
+ from: string,
543
+ to: string,
544
+ specs: readonly string[],
545
+ ): { ok: true; changed: string[]; outside: string[] } | { ok: false; stderr: string } {
546
+ const diff = (only: readonly string[]) =>
531
547
  gitRaw(root, [
532
548
  "diff",
533
549
  "--name-only",
534
550
  "-z",
535
551
  "--no-renames",
536
- o.from,
537
- o.to,
538
- ...(specs.length ? ["--", ...specs] : []),
552
+ from,
553
+ to,
554
+ ...(only.length ? ["--", ...only] : []),
539
555
  ]);
540
- const all = changed([]);
541
- const book = changed(bookPathspecs(o.month, o.fid, "pr"));
542
- if (all.status !== 0 || book.status !== 0) {
543
- return { kind: "diff-failed", stderr: all.status !== 0 ? all.stderr : book.stderr };
544
- }
556
+ const all = diff([]);
557
+ if (all.status !== 0) return { ok: false, stderr: all.stderr };
558
+ const changed = [...new Set(nulList(all.stdout))].sort();
559
+ // No specs = nothing allowed: `git diff` with no pathspec would match every path.
560
+ if (specs.length === 0) return { ok: true, changed, outside: changed };
561
+ const book = diff(specs);
562
+ if (book.status !== 0) return { ok: false, stderr: book.stderr };
545
563
  const allowed = new Set(nulList(book.stdout));
546
- const outside = [...new Set(nulList(all.stdout).filter((p) => !allowed.has(p)))].sort();
547
- return outside.length ? { kind: "outside", outside } : { kind: "ok" };
564
+ return { ok: true, changed, outside: changed.filter((p) => !allowed.has(p)) };
548
565
  }
549
566
 
550
567
  function onlyBookkeeping(ctx: RunContext): number {