@cbartens/bkit 5.4.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 (111) hide show
  1. package/.bkit/README.md +18 -6
  2. package/.bkit/core/.agents/rules.md +7 -8
  3. package/.bkit/core/.bkit/README.md +17 -5
  4. package/.bkit/core/.bkit/cloud.md +44 -13
  5. package/.bkit/core/.bkit/comparison.md +2 -2
  6. package/.bkit/core/.bkit/install.md +16 -14
  7. package/.bkit/core/.bkit/pipeline.md +3 -1
  8. package/.bkit/core/.bkit/prompts.md +12 -9
  9. package/.bkit/core/.bkit/providers.md +6 -6
  10. package/.bkit/core/.bkit/templates.md +12 -6
  11. package/.bkit/core/.bkit/trackers.md +89 -34
  12. package/.bkit/core/.bkit/workflows.md +42 -38
  13. package/.bkit/core/AGENTS.md +2 -2
  14. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  15. package/.bkit/core/docs/templates/bkit-audit-issues.md +22 -6
  16. package/.bkit/core/engine/checks/after/auth.ts +88 -45
  17. package/.bkit/core/engine/checks/after/github.ts +18 -5
  18. package/.bkit/core/engine/checks/after/index.ts +1 -1
  19. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  20. package/.bkit/core/engine/checks/before/env.ts +28 -18
  21. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  22. package/.bkit/core/engine/checks/tips/catalogue.ts +15 -2
  23. package/.bkit/core/engine/cli.ts +7 -5
  24. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  25. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  26. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  27. package/.bkit/core/engine/commands/workflow/issues.ts +35 -16
  28. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  29. package/.bkit/core/engine/commands/workflow/prs.ts +3 -1
  30. package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
  31. package/.bkit/core/engine/commands/workflow/roadmap.ts +5 -1
  32. package/.bkit/core/engine/commands/workflow/steps.ts +2 -2
  33. package/.bkit/core/engine/commands/workflow/workflows.ts +9 -4
  34. package/.bkit/core/engine/install/manifest.ts +31 -10
  35. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  36. package/.bkit/core/engine/install/modules/core.ts +82 -4
  37. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  38. package/.bkit/core/engine/install/write.ts +37 -1
  39. package/.bkit/core/engine/render/trackers.ts +35 -23
  40. package/.bkit/core/engine/shared/egress.ts +6 -0
  41. package/.bkit/core/engine/shared/settings.ts +88 -1
  42. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  43. package/.bkit/core/prompts/bkit-audit-generate.md +42 -12
  44. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  45. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  46. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  47. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  48. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  49. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  50. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  51. package/.bkit/core/prompts/bkit-design-generate.md +2 -1
  52. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  53. package/.bkit/core/prompts/bkit-utility-update-decisions.md +3 -1
  54. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +3 -1
  55. package/.bkit/core/prompts/bkit-utility-update-documentation.md +11 -1
  56. package/.bkit/core/prompts/bkit-utility-update-failures.md +3 -1
  57. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +3 -1
  58. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +9 -2
  59. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  60. package/.bkit/core/workflows/bkit-auto.md +19 -6
  61. package/.bkit/core/workflows/bkit-build.md +59 -17
  62. package/.bkit/core/workflows/bkit-debug.md +64 -20
  63. package/.bkit/core/workflows/bkit-design.md +83 -28
  64. package/.bkit/core/workflows/bkit-plan.md +61 -20
  65. package/.bkit/core/workflows/bkit-ship.md +48 -18
  66. package/.bkit/shared/.bkit/.env.example +8 -0
  67. package/.bkit/shared/.claude/settings.json +3 -1
  68. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  69. package/.bkit/shared/.cursor/mcp.json +11 -4
  70. package/.bkit/shared/.mcp.json +11 -4
  71. package/.bkit/shared/.opencode/opencode.json +2 -0
  72. package/.bkit/shared/docs/deployments.md +15 -4
  73. package/.bkit/shared/docs/security.md +1 -1
  74. package/.bkit/shared/docs/testing.md +3 -3
  75. package/.bkit/templates/.github/renovate.json5 +1 -1
  76. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -54
  77. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  78. package/.bkit/templates/.husky/pre-commit +4 -4
  79. package/.bkit/templates/.husky/pre-push +62 -12
  80. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
  81. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
  82. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  83. package/CHANGELOG.md +37 -1
  84. package/README.md +7 -6
  85. package/dist/checks/after/auth.js +81 -45
  86. package/dist/checks/after/github.js +17 -5
  87. package/dist/checks/after/index.js +1 -1
  88. package/dist/checks/after/tools.js +1 -1
  89. package/dist/checks/before/env.js +24 -17
  90. package/dist/checks/before/mcp.js +4 -2
  91. package/dist/checks/tips/catalogue.js +14 -2
  92. package/dist/cli.js +7 -5
  93. package/dist/commands/ci/ci.js +100 -0
  94. package/dist/commands/install/uninstall.js +42 -0
  95. package/dist/commands/workflow/fids.js +22 -15
  96. package/dist/commands/workflow/issues.js +28 -15
  97. package/dist/commands/workflow/ledgers.js +26 -11
  98. package/dist/commands/workflow/prs.js +3 -1
  99. package/dist/commands/workflow/repo.js +5 -0
  100. package/dist/commands/workflow/roadmap.js +3 -1
  101. package/dist/commands/workflow/steps.js +2 -2
  102. package/dist/commands/workflow/workflows.js +9 -4
  103. package/dist/install/manifest.js +30 -10
  104. package/dist/install/modules/cloud.js +3 -1
  105. package/dist/install/modules/core.js +82 -5
  106. package/dist/install/modules/opencode.js +6 -0
  107. package/dist/install/write.js +26 -2
  108. package/dist/render/trackers.js +34 -20
  109. package/dist/shared/egress.js +6 -0
  110. package/dist/shared/settings.js +39 -0
  111. package/package.json +11 -2
@@ -834,6 +834,12 @@ export async function runUninstall(
834
834
  }
835
835
  }
836
836
 
837
+ // Targeted uninstall: drop the `bkit.*` keys the removed module records, so its advisories
838
+ // stop firing. Core keeps every other key.
839
+ if (!moduleList.includes("core")) {
840
+ stripModuleBkitKeys(moduleList, ctx, result);
841
+ }
842
+
837
843
  // Clean up .agents/ bkit-prefix mirror files
838
844
  // (.claude/commands/bkit-*.md, .claude/agents/bkit-*.md, .opencode/agents/bkit-*.md, etc.)
839
845
  // A dry run lists the same paths in result.deleted and removes nothing.
@@ -1029,6 +1035,46 @@ export async function runUninstall(
1029
1035
  return result;
1030
1036
  }
1031
1037
 
1038
+ /** `package.json` `bkit.*` keys each module records on install. */
1039
+ const MODULE_BKIT_KEYS: Partial<Record<ModuleName, readonly string[]>> = {
1040
+ cloud: ["cloudAgents"],
1041
+ opencode: ["opencodeProvider", "opencodeProviders"],
1042
+ };
1043
+
1044
+ /**
1045
+ * Remove the `bkit.*` keys recorded by the modules in `moduleList` from the consumer's
1046
+ * package.json, keeping its indent. Lists each removed key in `result.stripped`; a dry run
1047
+ * lists without writing.
1048
+ */
1049
+ function stripModuleBkitKeys(
1050
+ moduleList: ModuleName[],
1051
+ ctx: UninstallContext,
1052
+ result: UninstallResult,
1053
+ ): void {
1054
+ const keys = moduleList.flatMap((m) => MODULE_BKIT_KEYS[m] ?? []);
1055
+ if (keys.length === 0) return;
1056
+ const pkgPath = path.join(ctx.cwd, "package.json");
1057
+ if (!fs.existsSync(pkgPath)) return;
1058
+ const raw = fs.readFileSync(pkgPath, "utf-8");
1059
+ const parsed = parseJson(raw);
1060
+ const pkg = parsed.ok ? (parsed.value as Record<string, unknown> | null) : null;
1061
+ if (pkg === null || !isJsonObject(pkg.bkit as JsonValue)) return;
1062
+ const bkit = pkg.bkit as Record<string, unknown>;
1063
+ const present = keys.filter((k) => k in bkit);
1064
+ if (present.length === 0) return;
1065
+ for (const k of present) {
1066
+ delete bkit[k];
1067
+ result.stripped.push(`package.json#bkit.${k}`);
1068
+ }
1069
+ console.log(
1070
+ `${ctx.logPrefix}${ctx.dryRun ? " [dry-run]" : ""} package.json: removed bkit.${present.join(", bkit.")}`,
1071
+ );
1072
+ if (ctx.dryRun) return;
1073
+ const indentMatch = raw.match(/\n([ \t]+)"/);
1074
+ const indent = indentMatch ? indentMatch[1] : " ";
1075
+ fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + "\n", "utf-8");
1076
+ }
1077
+
1032
1078
  // ---------------------------------------------------------------------------
1033
1079
  // runSurgicalOpencodeUninstall — remove exactly ONE provider block
1034
1080
  // ---------------------------------------------------------------------------
@@ -6,8 +6,9 @@
6
6
  // it is checked before first use. Its shape follows the tracker that minted it:
7
7
  // github {N}-{slug} ^[0-9]+-[a-z0-9-]+$
8
8
  // linear {team}-{N}-{slug} ^[a-z]+-[0-9]+-[a-z0-9-]+$ (issue id lowercased first)
9
+ // jira {project}-{N}-{slug} ^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$ (issue key lowercased first)
9
10
  // none any slug ^[a-z0-9][a-z0-9-]*$ (no tracker shape; still path-safe)
10
- // any github or linear ^([0-9]+|[a-z]+-[0-9]+)-[a-z0-9-]+$ (auto's CI_DEV allowlist)
11
+ // any any tracker's shape ^([0-9]+|[a-z][a-z0-9]*-[0-9]+)-[a-z0-9-]+$ (auto's CI_DEV allowlist)
11
12
 
12
13
  import * as fs from "node:fs";
13
14
  import * as path from "node:path";
@@ -22,10 +23,16 @@ export type FidTracker = IssueTracker | "any";
22
23
  export const FID_PATTERNS: Readonly<Record<FidTracker, RegExp>> = {
23
24
  github: /^[0-9]+-[a-z0-9-]+$/,
24
25
  linear: /^[a-z]+-[0-9]+-[a-z0-9-]+$/,
26
+ jira: /^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$/,
25
27
  none: /^[a-z0-9][a-z0-9-]*$/,
26
- any: /^([0-9]+|[a-z]+-[0-9]+)-[a-z0-9-]+$/,
28
+ any: /^([0-9]+|[a-z][a-z0-9]*-[0-9]+)-[a-z0-9-]+$/,
27
29
  };
28
30
 
31
+ /** Trackers whose issue id is a `{KEY}-{N}` key, carried lowercased in the FID. */
32
+ const KEYED: ReadonlySet<FidTracker> = new Set(["linear", "jira"]);
33
+ /** The uppercase issue key each keyed tracker mints. */
34
+ const ISSUE_KEY = { linear: /^[A-Z]+-[0-9]+$/, jira: /^[A-Z][A-Z0-9]+-[0-9]+$/ } as const;
35
+
29
36
  /** The slug every recovered FID must pass before it touches a path (auto's branch fallback). */
30
37
  const SLUG = FID_PATTERNS.none;
31
38
 
@@ -36,7 +43,7 @@ export const EXIT_SEVERAL = 4;
36
43
 
37
44
  /**
38
45
  * Features already logged for an issue: every `docs/plans/{YYYYMM}/logs/{issue}-*`
39
- * folder, the issue id lowercased (a Linear FID carries it lowercased). Sorted, unique.
46
+ * folder, the issue id lowercased (a Linear or Jira FID carries it lowercased). Sorted, unique.
40
47
  */
41
48
  export function logged(root: string, issue: string): string[] {
42
49
  const key = `${issue.replace(/^#/, "").toLowerCase()}-`;
@@ -87,29 +94,29 @@ function trackerFlag(value: string | undefined, cwd: string, allowAny: boolean):
87
94
  if (!t) {
88
95
  throw new CommandError(
89
96
  EXIT.USAGE,
90
- `--tracker must be github, linear, none${allowAny ? ", any" : ""}; got "${value}"`,
97
+ `--tracker must be github, linear, jira, none${allowAny ? ", any" : ""}; got "${value}"`,
91
98
  );
92
99
  }
93
100
  return t;
94
101
  }
95
102
 
96
- /** Linear issue ids arrive uppercase (`ABC-123`); the FID carries them lowercased. */
103
+ /** Linear and Jira issue ids arrive uppercase (`ABC-123`); the FID carries them lowercased. */
97
104
  export const normaliseFid = (fid: string, tracker: FidTracker) =>
98
- tracker === "linear" ? fid.toLowerCase() : fid;
105
+ KEYED.has(tracker) ? fid.toLowerCase() : fid;
99
106
 
100
107
  /**
101
108
  * The tracker issue id a FID embeds, or null when it embeds none:
102
- * github the leading numeric segment, linear the first two segments uppercased.
109
+ * github the leading numeric segment, linear and jira the first two segments uppercased.
103
110
  */
104
111
  export function issueIdOf(fid: string, tracker: FidTracker): string | null {
105
112
  const [first = "", second = ""] = fid.split("-");
106
113
  if (tracker === "github") return /^[0-9]+$/.test(first) ? first : null;
107
- if (tracker === "linear") {
114
+ if (KEYED.has(tracker)) {
108
115
  const id = `${first}-${second}`.toUpperCase();
109
- return /^[A-Z]+-[0-9]+$/.test(id) ? id : null;
116
+ return ISSUE_KEY[tracker as "linear" | "jira"].test(id) ? id : null;
110
117
  }
111
118
  if (tracker === "any") {
112
- const m = /^([0-9]+|[a-z]+-[0-9]+)(?=-)/.exec(fid);
119
+ const m = /^([0-9]+|[a-z][a-z0-9]*-[0-9]+)(?=-)/.exec(fid);
113
120
  return m ? m[1]!.toUpperCase() : null;
114
121
  }
115
122
  return null;
@@ -119,6 +126,7 @@ export function issueIdOf(fid: string, tracker: FidTracker): string | null {
119
126
  const MARKERS: Readonly<Record<IssueTracker, RegExp>> = {
120
127
  github: /<!-- bkit:issue=#([0-9]+) bkit:fid=(\S+) -->/,
121
128
  linear: /<!-- bkit:issue=([A-Za-z]+-[0-9]+) bkit:fid=(\S+) -->/,
129
+ jira: /<!-- bkit:issue=([A-Za-z][A-Za-z0-9]+-[0-9]+) bkit:fid=(\S+) -->/,
122
130
  none: /<!-- bkit:fid=(\S+) -->/,
123
131
  };
124
132
 
@@ -134,7 +142,7 @@ export function fromMarker(text: string, tracker: IssueTracker): ParsedFid | nul
134
142
  if (!m) return null;
135
143
  const fid = normaliseFid(m[m.length - 1]!, tracker);
136
144
  if (!FID_PATTERNS[tracker].test(fid)) return null;
137
- const issueId = tracker === "none" ? null : tracker === "linear" ? m[1]!.toUpperCase() : m[1]!;
145
+ const issueId = tracker === "none" ? null : KEYED.has(tracker) ? m[1]!.toUpperCase() : m[1]!;
138
146
  return { fid, issueId, source: "marker" };
139
147
  }
140
148
 
@@ -157,7 +165,7 @@ export function fromBranch(
157
165
  const TRACKER_FLAG: FlagSpec = {
158
166
  name: "tracker",
159
167
  type: "string",
160
- help: "github | linear | none (default: package.json bkit.issueTracker, else none)",
168
+ help: "github | linear | jira | none (default: package.json bkit.issueTracker, else none)",
161
169
  };
162
170
 
163
171
  export const fidsCommand: CommandSpec = {
@@ -168,10 +176,10 @@ export const fidsCommand: CommandSpec = {
168
176
  summary: "Validate a FID for the tracker: exit 0 valid, exit 1 not.",
169
177
  flags: [
170
178
  { name: "fid", type: "string", required: true, help: "feature id to check" },
171
- { ...TRACKER_FLAG, help: `${TRACKER_FLAG.help}; any = github or linear shape (CI_DEV)` },
179
+ { ...TRACKER_FLAG, help: `${TRACKER_FLAG.help}; any = any tracker's shape (CI_DEV)` },
172
180
  ],
173
181
  output: {
174
- fid: "the FID as checked (linear: lowercased)",
182
+ fid: "the FID as checked (linear, jira: lowercased)",
175
183
  tracker: "tracker the shape came from",
176
184
  valid: "true when the FID matches",
177
185
  pattern: "the regex checked",
@@ -267,7 +275,7 @@ export const fidsCommand: CommandSpec = {
267
275
  name: "issue",
268
276
  type: "string",
269
277
  required: true,
270
- help: "tracker issue id (github: 123 or #123; linear: ABC-123)",
278
+ help: "tracker issue id (github: 123 or #123; linear / jira: ABC-123)",
271
279
  },
272
280
  ],
273
281
  output: {
@@ -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;
@@ -201,15 +208,25 @@ export function transitionLabels(current: string[], t: LabelTransition) {
201
208
  }
202
209
 
203
210
  /**
204
- * Linear's issue state for the same transition, as the workflows set it: a
205
- * shipped or failed issue waits on a human ("In Review"); a phase
206
- * 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.
207
217
  */
208
- export function linearState(t: LabelTransition, board: string | undefined): string | null {
209
- if (t.phase === "merged" || t.failed === true) return "In Review";
210
- if (t.phase !== undefined) return "In Progress";
211
- if (board === "review") return "In Review";
212
- 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;
213
230
  return null;
214
231
  }
215
232
 
@@ -240,7 +257,8 @@ function boardPayload(
240
257
  const root = repoRoot(ctx.cwd);
241
258
  const tracker = readBkitConfig(root).issueTracker;
242
259
  if (tracker !== "github") {
243
- 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.");
244
262
  return { board: null, boardSkipped: `tracker-${tracker}` };
245
263
  }
246
264
  const gp = readBkitConfig(root).githubProject;
@@ -324,7 +342,7 @@ function labelsVerb(ctx: RunContext): number {
324
342
  labels,
325
343
  changed: add.length + remove.length > 0,
326
344
  autoRouteSuffix: labels.includes(AUTO_LABEL) ? AUTO_ROUTE_SUFFIX : "",
327
- linearState: linearState(t, board),
345
+ trackerState: trackerState(t, board, readBkitConfig(repoRoot(ctx.cwd))),
328
346
  board: payload,
329
347
  boardSkipped,
330
348
  });
@@ -616,7 +634,7 @@ export const issuesCommand: CommandSpec = {
616
634
  run: textVerb,
617
635
  },
618
636
  labels: {
619
- 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.",
620
638
  flags: [
621
639
  { name: "label", type: "string", repeatable: true, help: "a label the issue carries now" },
622
640
  {
@@ -639,7 +657,8 @@ export const issuesCommand: CommandSpec = {
639
657
  labels: "the full label set to write",
640
658
  changed: "whether add or remove is non-empty",
641
659
  autoRouteSuffix: `"${AUTO_ROUTE_SUFFIX}" when the label set carries ${AUTO_LABEL}, else ""`,
642
- 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",
643
662
  board: "projects payloads {addItem, listItems, updateItem}, or null",
644
663
  boardSkipped:
645
664
  "why board is null with --board: opted-out | not-configured | tracker-<name> | …",
@@ -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 {
@@ -169,11 +169,13 @@ function refFlag(value: FlagValue, flag: string): string {
169
169
  const FID_FORMAT: Record<IssueTracker, RegExp> = {
170
170
  github: /^[0-9]+-[a-z0-9-]+$/,
171
171
  linear: /^[a-z]+-[0-9]+-[a-z0-9-]+$/,
172
+ jira: /^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$/,
172
173
  none: /^[a-z0-9][a-z0-9-]*$/,
173
174
  };
174
175
  const ISSUE_FORMAT: Record<Exclude<IssueTracker, "none">, RegExp> = {
175
176
  github: /^[0-9]+$/,
176
177
  linear: /^[A-Z]+-[0-9]+$/,
178
+ jira: /^[A-Z][A-Z0-9]+-[0-9]+$/,
177
179
  };
178
180
 
179
181
  /** The PR-body marker line for this tracker (`.bkit/trackers.md` `pr-body-marker`). */
@@ -787,7 +789,7 @@ export const prsCommand: CommandSpec = {
787
789
  {
788
790
  name: "issue",
789
791
  type: "string",
790
- help: "issue id for the marker (github: 123 or #123; linear: ABC-123)",
792
+ help: "issue id for the marker (github: 123 or #123; linear / jira: ABC-123)",
791
793
  },
792
794
  BASE_FLAG,
793
795
  HEAD_FLAG,
@@ -13,6 +13,7 @@ import * as path from "node:path";
13
13
  import { parseRemoteUrlToSlug } from "../../ledgers/telemetry.js";
14
14
  import { DEV, EXIT, git, repoRoot, runGit, runTool, type CommandSpec } from "../lib.js";
15
15
  import { bkitVersionStatus } from "../../shared/bkit-latest.js";
16
+ import { readBkitConfig, trackerScope } from "../../shared/settings.js";
16
17
 
17
18
  /** Exit code: neither gh nor the origin remote named an owner/repo. */
18
19
  export const EXIT_NO_REPO = 3;
@@ -130,6 +131,10 @@ export const repoCommand: CommandSpec = {
130
131
  bkitOutdated:
131
132
  "true when bkitVersion is older than bkitLatest (null when either is unknown)",
132
133
  bkitAdvisory: "one line to show the user when bkitOutdated, else null",
134
+ trackerTeam: "package.json bkit.linear.team under linear, else null",
135
+ trackerProject:
136
+ "package.json bkit.linear.project under linear, bkit.jira.project under jira, else null",
137
+ trackerSite: "package.json bkit.jira.site under jira (the MCP cloudId), else null",
133
138
  },
134
139
  exitCodes: {
135
140
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -179,6 +184,7 @@ export const repoCommand: CommandSpec = {
179
184
  bkitLatest: latest.latest,
180
185
  bkitOutdated: latest.outdated,
181
186
  bkitAdvisory: latest.advisory,
187
+ ...trackerScope(readBkitConfig(root)),
182
188
  });
183
189
  if (branch === null && ctx.flags.allowDetached !== true) {
184
190
  ctx.log("HEAD is detached — no current branch");
@@ -60,6 +60,10 @@ const NOTES_POST_PLACEHOLDER = "## Notes\n\n_(end of the board — yours, never
60
60
  const BANNER =
61
61
  "> Generated tables — do not hand-edit the `bkit` tables; append to `.bkit/issues.jsonl` instead (an `ABANDONED` row hides a FID from every section). `## Notes` blocks are yours and are never overwritten. Everything above the first marker is also yours. notes-post is last. Analysis list length: `package.json` key `bkit.roadmapNext` (positive integer; absent or invalid → 25).";
62
62
 
63
+ /** Fixed related-utilities line; `@bkit-audit-generate` ends every run with the same text. */
64
+ export const RELATED_UTILITIES =
65
+ "> Related utilities, run on demand: `@bkit-utility-update-roadmap` ranks the next best items in `docs/roadmap.md`; `@bkit-utility-update-tracker` brings tracker issues in line with the tracker rules; `@bkit-utility-update-deferrals` and `@bkit-utility-update-failures` close ledger rows the code already resolved; `@bkit-utility-update-decisions`, `@bkit-utility-update-knowledge` and `@bkit-utility-update-documentation` correct ledgers and docs the code has since contradicted.";
66
+
63
67
  /** Newest SHIPPED rows on the board; older ones stay in the ledger. */
64
68
  export const SHIPPED_ON_BOARD = 10;
65
69
 
@@ -133,7 +137,7 @@ function table(rows: Row[]): string[] {
133
137
  }
134
138
 
135
139
  export function statusBlock(p: Projection, now: string): string {
136
- const out = [BANNER, "", "## bkit", "", `_(refreshed ${now})_`];
140
+ const out = [BANNER, "", RELATED_UTILITIES, "", "## bkit", "", `_(refreshed ${now})_`];
137
141
  for (const [bucket, , heading] of SECTIONS) out.push("", heading, "", ...table(p[bucket]));
138
142
  return out.join("\n");
139
143
  }
@@ -33,7 +33,7 @@ import {
33
33
  type FlagValue,
34
34
  type RunContext,
35
35
  } from "../lib.js";
36
- import { FID_PATTERNS, readIssueTracker } from "./fids.js";
36
+ import { FID_PATTERNS, normaliseFid, readIssueTracker } from "./fids.js";
37
37
  import { buildComment } from "./issues.js";
38
38
  import { readHolder, resolveMonth, workflowLockPath } from "./locks.js";
39
39
  import {
@@ -456,7 +456,7 @@ function gateChecks(cwd: string, o: GateOptions): Check[] {
456
456
 
457
457
  if (o.fid !== undefined) {
458
458
  const tracker = readIssueTracker(cwd);
459
- const fid = tracker === "linear" ? o.fid.toLowerCase() : o.fid;
459
+ const fid = normaliseFid(o.fid, tracker);
460
460
  add(
461
461
  `fid ${fid}`,
462
462
  FID_PATTERNS[tracker].test(fid)
@@ -38,6 +38,7 @@ import {
38
38
  type CoverageStats,
39
39
  } from "../../ledgers/telemetry.js";
40
40
  import { readBkitVersion } from "../../install/version-file.js";
41
+ import { readBkitConfig } from "../../shared/settings.js";
41
42
  import { gradeCompliance } from "../comply.js";
42
43
  import { landDir, pushToDev, type DevPush } from "../land.js";
43
44
  import {
@@ -62,7 +63,7 @@ import {
62
63
  AUTO_LABEL,
63
64
  AUTO_ROUTE_SUFFIX,
64
65
  buildComment,
65
- linearState,
66
+ trackerState,
66
67
  transitionLabels,
67
68
  } from "./issues.js";
68
69
  import { EXIT_EMPTY, commitBookkeeping, unionLedgers } from "./ledgers.js";
@@ -257,8 +258,10 @@ function failVerb(ctx: RunContext): number {
257
258
  }
258
259
  const merged = prState === "MERGED";
259
260
  const transition = merged ? { phase: "merged" } : { failed: true };
260
- const labels = transitionLabels(list(ctx.flags.label), transition).labels;
261
+ const current = list(ctx.flags.label);
262
+ const labels = transitionLabels(current, transition).labels;
261
263
  if (merged && !labels.includes("bkit:failed")) labels.push("bkit:failed");
264
+ const add = labels.filter((l) => !current.includes(l));
262
265
 
263
266
  // The failure comment, when the step is named.
264
267
  let comment: string | null = null;
@@ -285,8 +288,9 @@ function failVerb(ctx: RunContext): number {
285
288
  handoverNeeded:
286
289
  token !== undefined &&
287
290
  (ctx.flags.maxExceeded === true || state.sentinels.length > 0 || state.soak),
291
+ add,
288
292
  labels,
289
- linearState: linearState(transition, undefined),
293
+ trackerState: trackerState(transition, undefined, readBkitConfig(repoRoot(ctx.cwd))),
290
294
  prState,
291
295
  comment,
292
296
  });
@@ -1460,9 +1464,10 @@ export const workflowsCommand: CommandSpec = {
1460
1464
  sentinels: "[{name, path}] sentinels that existed before this call removed them",
1461
1465
  handoverNeeded:
1462
1466
  "--max-exceeded, a sentinel existed, or a debug run in SOAK mode: write the abort handover",
1467
+ add: "labels in the set that the issue does not carry yet",
1463
1468
  labels:
1464
1469
  "the label set to write: the current labels plus bkit:failed (and bkit:merged for a merged ship PR)",
1465
- linearState: "the Linear state for the failed issue",
1470
+ trackerState: "the Linear or Jira state for the failed issue (null under github, none)",
1466
1471
  prState: "the --pr PR's state, or null",
1467
1472
  comment: "the failure comment body (with --step-number), else null",
1468
1473
  },
@@ -53,14 +53,16 @@ export type ModuleName =
53
53
 
54
54
  /**
55
55
  * Issue-tracker providers supported by `bkit install --tracker=<name>`.
56
- * - `github` — GitHub Issues + Projects v2 (default).
57
- * - `linear` — Linear (opt-in).
58
- * - `none` — no tracker wired; workflows skip tracker calls with one-line log.
56
+ * - `github` — GitHub Issues + Projects v2.
57
+ * - `linear` — Linear.
58
+ * - `jira` — Jira Cloud through the Atlassian Rovo MCP server.
59
+ * - `none` — no tracker wired; workflows skip tracker calls with one-line log (default).
59
60
  *
60
- * Add a new value here when adding a provider section to `.bkit/trackers.md`.
61
- * See `.bkit/trackers.md` § "Adding a tracker (Jira, etc.)" in the Rules block.
61
+ * A new value needs its block in every tracker group of the workflow and prompt
62
+ * sources (`.bkit/trackers.md` § Marker contract) and a branch in
63
+ * `render/trackers.ts`.
62
64
  */
63
- export const ISSUE_TRACKERS = ["github", "linear", "none"] as const;
65
+ export const ISSUE_TRACKERS = ["github", "linear", "jira", "none"] as const;
64
66
  export type IssueTracker = (typeof ISSUE_TRACKERS)[number];
65
67
 
66
68
  /** Default tracker when consumer manifest has no `bkit.issueTracker` field. */
@@ -204,7 +206,9 @@ const CLAUDE_MANIFEST: ManifestEntry[] = [
204
206
  // ONE CHAIN. Each gate is the previous gate plus its own tier; the NAME and the
205
207
  // VALUE describe the same sequence. Tier vocabulary is the `bkit-ci.yml` job ids
206
208
  // (bkit-tests-static / -unit / -integration / -e2e / -live). Where a step is not a
207
- // tier (`format`, the ship gate) the name spells out the actual steps.
209
+ // tier (`format`, the ship gate) the name spells out the actual steps. One exception:
210
+ // `min` sits off the chain: the least a push runs, on a push that changes no code
211
+ // (`bkit.minPushPaths`); its steps are whatever that push can still break.
208
212
  //
209
213
  // The consumer owns every value: a turbo monorepo writes `turbo run … --filter`,
210
214
  // a Python repo writes `ruff check && pytest`. bkit never reads a value — only
@@ -228,18 +232,24 @@ const CLAUDE_MANIFEST: ManifestEntry[] = [
228
232
  // …-integration-e2e-live) are absent unless the consumer writes them. Each is one line
229
233
  // chaining its parent, e.g.
230
234
  // "bkit:gate:static-unit-integration": "pnpm bkit:gate:static-unit && pnpm test:integration"
231
- // `/bkit-build` and `/bkit-debug` run the DEEPEST gate that exists and record its name.
235
+ // `/bkit-build` and `/bkit-debug` run the DEEPEST gate that exists and record its name;
236
+ // `.husky/pre-push` runs `…-integration` when it exists (BKIT_PUSH_GATES).
232
237
  export const BKIT_GATE_SCRIPTS: Readonly<Record<string, string>> = {
233
238
  // `.husky/pre-commit`: prettier --write over staged files, and nothing else —
234
239
  // seconds, not minutes. Prose is a whole-repo scan, so it gates at pre-push.
235
240
  "bkit:gate:format": "pnpm lint-staged",
241
+ // `.husky/pre-push` on a min push (every file matches `bkit.minPushPaths`): no code, so
242
+ // no typecheck, lint or tests. Off the chain. Add any test that reads a min-push file.
243
+ "bkit:gate:min": "pnpm format:check && pnpm lint:prose && pnpm slop:delta",
236
244
  // Everything that needs no test runner. Every part has a matching step in the
237
245
  // bkit-tests-static CI job; audits/templates/template-ci-yml.test.ts fails when one is missing.
238
246
  // Callers: build's plan-execute loop between tasks, and the `.husky/pre-push` revert
239
247
  // path.
240
248
  "bkit:gate:static":
241
249
  "pnpm typecheck && pnpm lint && pnpm format:check && pnpm lint:prose && pnpm slop:delta",
242
- // The default local gate: `.husky/pre-push`, build Step 14, the remediates.
250
+ // The default local gate: `.husky/pre-push` (when no `…-integration` gate is declared),
251
+ // build Step 14, the remediates. `pnpm test` is the unit tier only: a test file the
252
+ // integration gate also runs must not match it.
243
253
  "bkit:gate:static-unit": "pnpm bkit:gate:static && pnpm test",
244
254
  // Ship's conflict-resolve, the only caller whose dependency graph may have just
245
255
  // been hand-merged (lockfile conflict) and whose tree no one has ever compiled.
@@ -276,13 +286,24 @@ export const BKIT_DEBUG_GATES: readonly string[] = [
276
286
  * Build stops at integration; E2E and live are not in this list.
277
287
  *
278
288
  * Neither entry is seeded: declaring `bkit:gate:static-unit-integration` opts the build
279
- * loop into the integration tier.
289
+ * loop and the pre-push hook into the integration tier.
280
290
  */
281
291
  export const BKIT_BUILD_GATES: readonly string[] = [
282
292
  "bkit:gate:static-unit-integration",
283
293
  "bkit:gate:static-unit",
284
294
  ];
285
295
 
296
+ /**
297
+ * What `.husky/pre-push` runs on a full push, in DESCENDING order — first one declared wins.
298
+ *
299
+ * Integration runs on push, never on commit; E2E and live stay in CI. The template hook
300
+ * reads package.json for the first entry itself (it cannot import this list).
301
+ */
302
+ export const BKIT_PUSH_GATES: readonly string[] = [
303
+ "bkit:gate:static-unit-integration",
304
+ "bkit:gate:static-unit",
305
+ ];
306
+
286
307
  /**
287
308
  * Runs ONE test file — `pnpm bkit:test:file <repo-relative path>` — and writes a JUnit
288
309
  * report to `$BKIT_TEST_REPORT`. `/bkit-build` records each task's red and audits its
@@ -86,7 +86,9 @@ export function runCloudModule(ctx: ModuleContext): void {
86
86
  CLOUD_WORKFLOW_ADOPT_STEP +
87
87
  " - Run `/install-github-app` (Claude Code CLI) to install the Claude GitHub App on your repo. This is required — `claude-code-action@v1` authenticates as the App via OIDC (`id-token: write`); without the App it fails at boot with an OIDC error.\n" +
88
88
  " - GitHub Actions permissions — flip BOTH org AND repo: Settings → Actions → General → Workflow permissions = **Read and write permissions** + tick **Allow GitHub Actions to create and approve pull requests**.\n" +
89
- " - Add `ANTHROPIC_API_KEY` to repo secrets (Settings → Secrets and variables → Actions). Used by `claude-code-action@v1` (job env keeps this vendor name; local `.bkit/.env` stores it as `BKIT_ANTHROPIC_API_KEY`).\n" +
89
+ " - Give `claude-code-action@v1` ONE claude credential (Settings → Secrets and variables → Actions):\n" +
90
+ " - the `ANTHROPIC_API_KEY` repo secret (job env keeps this vendor name; local `.bkit/.env` stores it as `BKIT_ANTHROPIC_API_KEY`), or\n" +
91
+ " - keyless workload identity federation: Claude Console → Settings → Workload identity → Connect workload → GitHub Actions creates the issuer, service account and federation rule; then set the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables (optional `ANTHROPIC_SERVICE_ACCOUNT_ID` / `ANTHROPIC_WORKSPACE_ID`). Leave `ANTHROPIC_API_KEY` unset — a set key wins over federation.\n" +
90
92
  " - Label the issue `bkit:auto` before pushing the build commit — without the label the CI auto-route exits no-op.\n\n" +
91
93
  "OPTIONAL (manual phase launch): after `/install-github-app`, comment `@claude /bkit-plan` (or any phase) on a GitHub issue/PR to launch it from the tracker UI. The App's generated `claude.yml` triggers on mention events; `bkit-cloud.yml` triggers on CI completion + `workflow_dispatch` — the two coexist.\n\n" +
92
94
  "Both the CI-driven path and the `@claude` mention path invoke the same `/bkit-auto` orchestrator (mirrored to `.claude/commands/bkit-auto.md` on each `pnpm bkit install`).",