@cbartens/bkit 5.4.0 → 5.5.1

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 (125) hide show
  1. package/.bkit/README.md +19 -7
  2. package/.bkit/core/.agents/rules.md +24 -9
  3. package/.bkit/core/.bkit/README.md +18 -6
  4. package/.bkit/core/.bkit/cloud.md +46 -15
  5. package/.bkit/core/.bkit/comparison.md +2 -2
  6. package/.bkit/core/.bkit/install.md +19 -18
  7. package/.bkit/core/.bkit/pipeline.md +3 -1
  8. package/.bkit/core/.bkit/prompts.md +38 -20
  9. package/.bkit/core/.bkit/providers.md +6 -6
  10. package/.bkit/core/.bkit/templates.md +44 -13
  11. package/.bkit/core/.bkit/trackers.md +99 -35
  12. package/.bkit/core/.bkit/workflows.md +50 -45
  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/ci-yml.ts +0 -1
  18. package/.bkit/core/engine/checks/after/github.ts +42 -78
  19. package/.bkit/core/engine/checks/after/index.ts +1 -6
  20. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  21. package/.bkit/core/engine/checks/before/env.ts +28 -18
  22. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  23. package/.bkit/core/engine/checks/tips/catalogue.ts +15 -2
  24. package/.bkit/core/engine/checks/tips/index.ts +5 -2
  25. package/.bkit/core/engine/cli.ts +7 -5
  26. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  27. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  28. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  29. package/.bkit/core/engine/commands/workflow/issues.ts +61 -63
  30. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  31. package/.bkit/core/engine/commands/workflow/prs.ts +3 -1
  32. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  33. package/.bkit/core/engine/commands/workflow/roadmap.ts +5 -1
  34. package/.bkit/core/engine/commands/workflow/steps.ts +2 -2
  35. package/.bkit/core/engine/commands/workflow/workflows.ts +9 -4
  36. package/.bkit/core/engine/commands/workflow/worktrees.ts +91 -14
  37. package/.bkit/core/engine/install/manifest.ts +31 -10
  38. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  39. package/.bkit/core/engine/install/modules/core.ts +153 -4
  40. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  41. package/.bkit/core/engine/install/write.ts +37 -1
  42. package/.bkit/core/engine/render/trackers.ts +35 -23
  43. package/.bkit/core/engine/shared/egress.ts +6 -0
  44. package/.bkit/core/engine/shared/settings.ts +130 -11
  45. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  46. package/.bkit/core/prompts/bkit-audit-generate.md +42 -12
  47. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  48. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  49. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  50. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  51. package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -0
  52. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  53. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  54. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  55. package/.bkit/core/prompts/bkit-design-generate.md +4 -1
  56. package/.bkit/core/prompts/bkit-plan-generate.md +5 -3
  57. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  58. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  59. package/.bkit/core/prompts/bkit-utility-update-decisions.md +3 -1
  60. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +3 -1
  61. package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
  62. package/.bkit/core/prompts/bkit-utility-update-failures.md +3 -1
  63. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +3 -1
  64. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +9 -2
  65. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  66. package/.bkit/core/workflows/bkit-auto.md +19 -6
  67. package/.bkit/core/workflows/bkit-build.md +59 -17
  68. package/.bkit/core/workflows/bkit-debug.md +64 -20
  69. package/.bkit/core/workflows/bkit-design.md +83 -28
  70. package/.bkit/core/workflows/bkit-plan.md +61 -20
  71. package/.bkit/core/workflows/bkit-ship.md +48 -18
  72. package/.bkit/shared/.bkit/.env.example +8 -0
  73. package/.bkit/shared/.claude/settings.json +3 -1
  74. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  75. package/.bkit/shared/.cursor/mcp.json +11 -4
  76. package/.bkit/shared/.mcp.json +11 -4
  77. package/.bkit/shared/.opencode/opencode.json +2 -0
  78. package/.bkit/shared/docs/deployments.md +6 -7
  79. package/.bkit/shared/docs/security.md +1 -1
  80. package/.bkit/shared/docs/testing.md +13 -5
  81. package/.bkit/templates/.github/renovate.json5 +1 -1
  82. package/.bkit/templates/.github/workflows/bkit-ci.yml +21 -115
  83. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  84. package/.bkit/templates/.husky/pre-commit +4 -4
  85. package/.bkit/templates/.husky/pre-push +107 -18
  86. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  87. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  88. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  89. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  90. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  91. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  92. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  93. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  94. package/CHANGELOG.md +67 -1
  95. package/README.md +16 -6
  96. package/dist/checks/after/auth.js +81 -45
  97. package/dist/checks/after/ci-yml.js +0 -1
  98. package/dist/checks/after/github.js +41 -76
  99. package/dist/checks/after/index.js +2 -7
  100. package/dist/checks/after/tools.js +1 -1
  101. package/dist/checks/before/env.js +24 -17
  102. package/dist/checks/before/mcp.js +4 -2
  103. package/dist/checks/tips/catalogue.js +14 -2
  104. package/dist/checks/tips/index.js +4 -2
  105. package/dist/cli.js +7 -5
  106. package/dist/commands/ci/ci.js +100 -0
  107. package/dist/commands/install/uninstall.js +42 -0
  108. package/dist/commands/workflow/fids.js +22 -15
  109. package/dist/commands/workflow/issues.js +53 -61
  110. package/dist/commands/workflow/ledgers.js +26 -11
  111. package/dist/commands/workflow/prs.js +3 -1
  112. package/dist/commands/workflow/repo.js +6 -0
  113. package/dist/commands/workflow/roadmap.js +3 -1
  114. package/dist/commands/workflow/steps.js +2 -2
  115. package/dist/commands/workflow/workflows.js +9 -4
  116. package/dist/commands/workflow/worktrees.js +74 -13
  117. package/dist/install/manifest.js +30 -10
  118. package/dist/install/modules/cloud.js +3 -1
  119. package/dist/install/modules/core.js +157 -5
  120. package/dist/install/modules/opencode.js +6 -0
  121. package/dist/install/write.js +26 -2
  122. package/dist/render/trackers.js +34 -20
  123. package/dist/shared/egress.js +6 -0
  124. package/dist/shared/settings.js +59 -7
  125. package/package.json +14 -3
@@ -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,12 @@ 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",
138
+ trackerBoard:
139
+ "{ownerType, owner, number} read from package.json bkit.github.project under github, else null",
133
140
  },
134
141
  exitCodes: {
135
142
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -179,6 +186,7 @@ export const repoCommand: CommandSpec = {
179
186
  bkitLatest: latest.latest,
180
187
  bkitOutdated: latest.outdated,
181
188
  bkitAdvisory: latest.advisory,
189
+ ...trackerScope(readBkitConfig(root)),
182
190
  });
183
191
  if (branch === null && ctx.flags.allowDetached !== true) {
184
192
  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
  },
@@ -8,7 +8,10 @@
8
8
  // reports it. `remove` is the close / cleanup half: it removes only a worktree a
9
9
  // workflow created, marked in the git common dir's outbox so the marker outlives
10
10
  // the worktree it describes, and with `--branch` deletes the feature branch
11
- // unless another worktree still holds it.
11
+ // unless another worktree still holds it. A new branch, and a resume rebase,
12
+ // use local `dev` when it is a fast-forward of `origin/dev`: dev pushes wait for
13
+ // a human, so local dev is routinely ahead, and a worktree without those commits
14
+ // builds against superseded work.
12
15
 
13
16
  import { spawnSync } from "node:child_process";
14
17
  import * as fs from "node:fs";
@@ -116,12 +119,42 @@ function shipBranch(root: string, fid: string, named: string | undefined, sessio
116
119
  return isSharedBranch(session) || session === "" ? feat : session;
117
120
  }
118
121
 
122
+ /**
123
+ * The ref a feature branch starts from and rebases onto: local `dev` when it is
124
+ * strictly ahead of `origin/dev` (a fast-forward of it), else `origin/dev`. With
125
+ * `log`, says why when the two differ. Fetch first for a current answer.
126
+ */
127
+ export function devBase(cwd: string, log?: (m: string) => void): string {
128
+ const local = git(cwd, ["rev-parse", "-q", "--verify", `refs/heads/${DEV}`]);
129
+ const remote = git(cwd, ["rev-parse", "-q", "--verify", `refs/remotes/${ORIGIN_DEV}`]);
130
+ if (local === null || remote === null || local === remote) return ORIGIN_DEV;
131
+ const count = (range: string) => git(cwd, ["rev-list", "--count", range]) ?? "?";
132
+ if (runGit(cwd, ["merge-base", "--is-ancestor", remote, local]).ok) {
133
+ log?.(
134
+ `local ${DEV} is ${count(`${remote}..${local}`)} commit(s) ahead of ${ORIGIN_DEV} — basing on local ${DEV}; push ${DEV} before the feature PR`,
135
+ );
136
+ return DEV;
137
+ }
138
+ if (!runGit(cwd, ["merge-base", "--is-ancestor", local, remote]).ok) {
139
+ log?.(
140
+ `local ${DEV} and ${ORIGIN_DEV} have diverged — basing on ${ORIGIN_DEV}; local ${DEV}'s ${count(`${remote}..${local}`)} commit(s) are not in this worktree`,
141
+ );
142
+ }
143
+ return ORIGIN_DEV;
144
+ }
145
+
119
146
  /**
120
147
  * `git worktree add` for `branch`: the local branch, else a tracking branch off
121
- * `origin`, else (when `mayCreate`) a new branch off a freshly fetched
122
- * `origin/dev`. Returns false when there was nothing to add and `mayCreate` is off.
148
+ * `origin`, else (when `mayCreate`) a new branch off `devBase` after a fresh
149
+ * fetch. Returns false when there was nothing to add and `mayCreate` is off.
123
150
  */
124
- function addWorktree(root: string, wt: string, branch: string, mayCreate: boolean): boolean {
151
+ function addWorktree(
152
+ root: string,
153
+ wt: string,
154
+ branch: string,
155
+ mayCreate: boolean,
156
+ log: (m: string) => void,
157
+ ): boolean {
125
158
  let args: string[];
126
159
  if (hasLocal(root, branch)) {
127
160
  args = [wt, branch];
@@ -135,7 +168,7 @@ function addWorktree(root: string, wt: string, branch: string, mayCreate: boolea
135
168
  args = [wt, "--track", "-b", branch, `origin/${branch}`];
136
169
  } else if (mayCreate) {
137
170
  fetchBranch(root, DEV);
138
- args = [wt, "-b", branch, ORIGIN_DEV];
171
+ args = [wt, "-b", branch, devBase(root, log)];
139
172
  } else {
140
173
  return false;
141
174
  }
@@ -180,6 +213,34 @@ function copyListed(root: string, wt: string, entries: string[], log: (m: string
180
213
  return { copied, copyMissing };
181
214
  }
182
215
 
216
+ /**
217
+ * `direnv allow` the worktree's `.envrc` when it matches the main checkout's
218
+ * byte for byte, so the worktree inherits the trust given there and nothing
219
+ * more; a differing file is left for a human to read. No `.envrc`, direnv
220
+ * missing or failing → false, narrated, never fatal.
221
+ */
222
+ function allowDirenv(root: string, wt: string, log: (m: string) => void): boolean {
223
+ const envrc = path.join(wt, ".envrc");
224
+ if (!fs.existsSync(envrc)) return false;
225
+ const main = path.join(root, ".envrc");
226
+ if (!fs.existsSync(main) || !fs.readFileSync(main).equals(fs.readFileSync(envrc))) {
227
+ log(
228
+ `direnv: ${envrc} differs from the main checkout's — not allowed; read it, then run direnv allow`,
229
+ );
230
+ return false;
231
+ }
232
+ const res = spawnSync("direnv", ["allow", wt], { cwd: wt, encoding: "utf-8" });
233
+ if (res.error || res.status === 127) {
234
+ log("direnv: not installed — run direnv allow in the worktree once it is");
235
+ return false;
236
+ }
237
+ if (res.status !== 0) {
238
+ log(`direnv allow failed (exit ${res.status}): ${(res.stderr ?? "").trim()}`);
239
+ return false;
240
+ }
241
+ return true;
242
+ }
243
+
183
244
  /** Run the frozen install in `wt`; the exit status, with a spawn failure read as "could not run". */
184
245
  function install(wt: string, log: (m: string) => void): number {
185
246
  const [cmd, ...args] = installCommand({ frozen: true });
@@ -331,12 +392,16 @@ export const worktreesCommand: CommandSpec = {
331
392
  mode: "created | resumed | adopted",
332
393
  owned: "the .worktree-owned marker is present (a workflow created this worktree)",
333
394
  rebaseConflict:
334
- "a resume rebase onto origin/dev stopped on a conflict and is left in progress",
395
+ "a resume rebase onto baseRef stopped on a conflict and is left in progress",
335
396
  sentinel: "the .rebase-failed sentinel written on a failed rebase, else null",
336
397
  logDir: "docs/plans/{month}/logs/{fid} under worktreePath (created)",
337
- baseSha: "git merge-base origin/dev HEAD at worktreePath, or null",
398
+ baseRef:
399
+ "dev when local dev is a fast-forward of origin/dev (unpushed commits), else origin/dev",
400
+ baseSha: "git merge-base baseRef HEAD at worktreePath, or null",
338
401
  copied: "worktree copy entries copied from the main checkout",
339
402
  copyMissing: "worktree copy entries absent from the main checkout",
403
+ direnvAllowed:
404
+ "direnv allow ran on the worktree's .envrc (present and identical to the main checkout's)",
340
405
  installed: "dependencies were installed",
341
406
  },
342
407
  exitCodes: {
@@ -415,7 +480,7 @@ export const worktreesCommand: CommandSpec = {
415
480
  mode = "resumed";
416
481
  } else if (workflow !== "debug" || session !== target) {
417
482
  // Debug adopts an existing feat/{fid}; it never mints a branch of its own.
418
- if (addWorktree(root, wtDir, target, workflow !== "debug")) mode = "created";
483
+ if (addWorktree(root, wtDir, target, workflow !== "debug", ctx.log)) mode = "created";
419
484
  }
420
485
  }
421
486
  const wt = mode === "adopted" ? root : wtDir;
@@ -451,16 +516,22 @@ export const worktreesCommand: CommandSpec = {
451
516
  // Cleared before every attempt: a sentinel left by an earlier run would
452
517
  // send this one to the Failure Path after a clean rebase.
453
518
  fs.rmSync(sentinelPath, { force: true });
454
- let failure: { conflict: boolean; detail: string } | undefined;
519
+ let failure: { conflict: boolean; detail: string; onto: string } | undefined;
455
520
  if (rebaseInProgress(wt)) {
456
- failure = { conflict: true, detail: "a rebase is already in progress" };
521
+ failure = {
522
+ conflict: true,
523
+ detail: "a rebase is already in progress",
524
+ onto: devBase(wt),
525
+ };
457
526
  } else {
458
527
  fetchBranch(wt, DEV);
459
- const rb = runGit(wt, ["rebase", "--rebase-merges", ORIGIN_DEV]);
528
+ const onto = devBase(wt, ctx.log);
529
+ const rb = runGit(wt, ["rebase", "--rebase-merges", onto]);
460
530
  if (!rb.ok) {
461
531
  failure = {
462
532
  conflict: rebaseInProgress(wt),
463
533
  detail: [rb.stdout, rb.stderr].filter(Boolean).join("\n"),
534
+ onto,
464
535
  };
465
536
  }
466
537
  }
@@ -468,10 +539,12 @@ export const worktreesCommand: CommandSpec = {
468
539
  fs.mkdirSync(logDir, { recursive: true });
469
540
  fs.appendFileSync(
470
541
  path.join(logDir, "rebase-resolve-log.md"),
471
- `[bkit-worktrees] ${new Date().toISOString()} rebase onto ${ORIGIN_DEV} stopped\n${failure.detail}\n`,
542
+ `[bkit-worktrees] ${new Date().toISOString()} rebase onto ${failure.onto} stopped\n${failure.detail}\n`,
472
543
  );
473
544
  fs.writeFileSync(sentinelPath, "");
474
- ctx.log(`rebase onto ${ORIGIN_DEV} failed in ${wt}: ${failure.detail.split("\n")[0]}`);
545
+ ctx.log(
546
+ `rebase onto ${failure.onto} failed in ${wt}: ${failure.detail.split("\n")[0]}`,
547
+ );
475
548
  rebaseConflict = failure.conflict;
476
549
  sentinel = sentinelPath;
477
550
  }
@@ -486,9 +559,11 @@ export const worktreesCommand: CommandSpec = {
486
559
  const { copied, copyMissing } = done
487
560
  ? copyListed(root, wt, config.worktreeCopy, ctx.log)
488
561
  : { copied: [], copyMissing: [] };
562
+ const direnvAllowed = done && allowDirenv(root, wt, ctx.log);
489
563
  const wantInstall = done && config.worktreeInstall;
490
564
  const installStatus = wantInstall ? install(wt, ctx.log) : 0;
491
565
 
566
+ const baseRef = devBase(wt);
492
567
  ctx.emit({
493
568
  worktreePath: wt,
494
569
  repoRoot: root,
@@ -498,9 +573,11 @@ export const worktreesCommand: CommandSpec = {
498
573
  rebaseConflict,
499
574
  sentinel,
500
575
  logDir,
501
- baseSha: git(wt, ["merge-base", ORIGIN_DEV, "HEAD"]),
576
+ baseRef,
577
+ baseSha: git(wt, ["merge-base", baseRef, "HEAD"]),
502
578
  copied,
503
579
  copyMissing,
580
+ direnvAllowed,
504
581
  installed: wantInstall && installStatus === 0,
505
582
  });
506
583
  if (sentinel !== null)
@@ -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`).",
@@ -17,8 +17,9 @@ import { listFilesRecursive, syncTemplateCopies } from "../template-copies.js";
17
17
  import { PAYLOAD_LINK_RELPATHS, syncPayloadLinks } from "../payload-links.js";
18
18
  import { writeNetworkAllowlist } from "../network-allowlist.js";
19
19
  import type { PreflightFinding } from "../../checks/before/index.js";
20
- import { readJsonFile } from "../../shared/json.js";
20
+ import { parseJson, readJsonFile } from "../../shared/json.js";
21
21
  import { readInstallingVersion } from "../../shared/package-json.js";
22
+ import { CONFIG_DEFAULTS } from "../../shared/settings.js";
22
23
  import {
23
24
  getCoreRoot,
24
25
  getSharedRoot,
@@ -29,6 +30,7 @@ import {
29
30
  getInstallManifest,
30
31
  BKIT_GATE_SCRIPTS,
31
32
  BKIT_OPTIONAL_GATES,
33
+ BKIT_PUSH_GATES,
32
34
  BKIT_TEST_FILE_SCRIPT,
33
35
  } from "../manifest.js";
34
36
  import type { ModuleContext } from "./index.js";
@@ -392,9 +394,117 @@ export function seedCorePackageJsonScripts(
392
394
  written.push("package.json");
393
395
  console.log(`${logPrefix} ${tag}core: package.json scripts added [${gates.added.join(", ")}]`);
394
396
  }
397
+ if (migrateLinearTeamKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
398
+ written.push("package.json");
399
+ }
400
+ if (migrateGithubProjectKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
401
+ written.push("package.json");
402
+ }
395
403
  return written;
396
404
  }
397
405
 
406
+ /** Rewrite package.json with `pkg`, keeping the file's indent and trailing newline. */
407
+ function writePackageJsonLike(raw: string, pkg: unknown): void {
408
+ const indentMatch = raw.match(/\n([ \t]+)"/);
409
+ const indent = indentMatch ? indentMatch[1] : " ";
410
+ const trailingNewline = raw.endsWith("\n") ? "\n" : "";
411
+ fs.writeFileSync("package.json", JSON.stringify(pkg, null, indent) + trailingNewline, "utf-8");
412
+ }
413
+
414
+ // Status option ids of GitHub's Kanban and Team planning board templates; every board
415
+ // made from one carries the same ids.
416
+ const TEMPLATE_STATUS_OPTIONS: Readonly<Record<string, string>> = {
417
+ "47fc9ee4": "In progress",
418
+ df73e18b: "In review",
419
+ };
420
+
421
+ // Migration (up to 5.4.x installs, `docs/migrations.md`): the board lived at
422
+ // `bkit.githubProject` as `{owner, number, statusFieldId, *OptionId}`, org boards only; it
423
+ // is `bkit.github.project`, the board URL, with Status set by option name from
424
+ // `bkit.github.progress` / `review`. An existing `bkit.github.project` wins over the old
425
+ // key. Returns true when package.json changed.
426
+ export function migrateGithubProjectKey(dryRun: boolean, ws: WriteSet, logPrefix: string): boolean {
427
+ const pkgPath = "package.json";
428
+ if (!fs.existsSync(pkgPath)) return false;
429
+ const raw = fs.readFileSync(pkgPath, "utf-8");
430
+ const parsed = parseJson(raw);
431
+ if (!parsed.ok) return false;
432
+ const pkg = parsed.value as Record<string, unknown>;
433
+ const bkit = pkg.bkit;
434
+ if (bkit === null || typeof bkit !== "object" || Array.isArray(bkit)) return false;
435
+ const cfg = bkit as Record<string, unknown>;
436
+ if (!Object.prototype.hasOwnProperty.call(cfg, "githubProject")) return false;
437
+ const old = cfg.githubProject;
438
+ const github =
439
+ cfg.github !== null && typeof cfg.github === "object" && !Array.isArray(cfg.github)
440
+ ? (cfg.github as Record<string, unknown>)
441
+ : {};
442
+ const unnamed: ("progress" | "review")[] = [];
443
+ if (github.project === undefined) {
444
+ if (old === false) github.project = false;
445
+ else if (old !== null && typeof old === "object" && !Array.isArray(old)) {
446
+ const board = old as Record<string, unknown>;
447
+ const owner = typeof board.owner === "string" ? board.owner.trim() : "";
448
+ const number = Number(board.number);
449
+ if (owner !== "" && Number.isInteger(number) && number > 0) {
450
+ github.project = `https://github.com/orgs/${owner}/projects/${number}`;
451
+ for (const [moment, key] of [
452
+ ["progress", "progressOptionId"],
453
+ ["review", "reviewOptionId"],
454
+ ] as const) {
455
+ const id = board[key];
456
+ if (typeof id !== "string" || id.trim() === "") continue;
457
+ const name = TEMPLATE_STATUS_OPTIONS[id.trim()];
458
+ if (name === undefined) unnamed.push(moment);
459
+ else if (github[moment] === undefined && name !== CONFIG_DEFAULTS.github[moment])
460
+ github[moment] = name;
461
+ }
462
+ }
463
+ }
464
+ }
465
+ delete cfg.githubProject;
466
+ if (Object.keys(github).length > 0) cfg.github = github;
467
+ ws.writes.push({ path: pkgPath, action: "update" });
468
+ if (!dryRun) writePackageJsonLike(raw, pkg);
469
+ const tag = dryRun ? "[dry-run] " : "";
470
+ console.log(`${logPrefix} ${tag}core: moved bkit.githubProject to bkit.github in package.json`);
471
+ for (const moment of unnamed)
472
+ console.log(
473
+ `${logPrefix} ${tag}core: bkit.githubProject named its ${moment} Status option by id; set bkit.github.${moment} to that option's name (default "${CONFIG_DEFAULTS.github[moment]}")`,
474
+ );
475
+ return true;
476
+ }
477
+
478
+ // Migration (up to 5.4.x installs, `docs/migrations.md`): the Linear team lived at
479
+ // `bkit.linearTeam`; it is `bkit.linear.team`, beside the project and state names. An
480
+ // existing `bkit.linear.team` wins over the old key. Returns true when package.json changed.
481
+ export function migrateLinearTeamKey(dryRun: boolean, ws: WriteSet, logPrefix: string): boolean {
482
+ const pkgPath = "package.json";
483
+ if (!fs.existsSync(pkgPath)) return false;
484
+ const raw = fs.readFileSync(pkgPath, "utf-8");
485
+ const parsed = parseJson(raw);
486
+ if (!parsed.ok) return false;
487
+ const pkg = parsed.value as Record<string, unknown>;
488
+ const bkit = pkg.bkit;
489
+ if (bkit === null || typeof bkit !== "object" || Array.isArray(bkit)) return false;
490
+ const cfg = bkit as Record<string, unknown>;
491
+ if (!Object.prototype.hasOwnProperty.call(cfg, "linearTeam")) return false;
492
+ const old = cfg.linearTeam;
493
+ const linear =
494
+ cfg.linear !== null && typeof cfg.linear === "object" && !Array.isArray(cfg.linear)
495
+ ? (cfg.linear as Record<string, unknown>)
496
+ : {};
497
+ if (linear.team === undefined && typeof old === "string" && old.trim() !== "") linear.team = old;
498
+ delete cfg.linearTeam;
499
+ if (Object.keys(linear).length > 0) cfg.linear = linear;
500
+ ws.writes.push({ path: pkgPath, action: "update" });
501
+ if (!dryRun) writePackageJsonLike(raw, pkg);
502
+ console.log(
503
+ `${logPrefix} ${dryRun ? "[dry-run] " : ""}core: moved bkit.linearTeam to bkit.linear.team in package.json`,
504
+ );
505
+ return true;
506
+ }
507
+
398
508
  // Tokens that follow `pnpm` in a gate value but are not package.json scripts: the
399
509
  // package manager's own subcommands (`install` in bkit:gate:install-static-unit-build,
400
510
  // `audit` / `outdated` in the bkit:deps:* pair) and node_modules binaries pnpm resolves
@@ -409,10 +519,33 @@ const PNPM_NOT_A_SCRIPT = new Set([
409
519
  "lint-staged",
410
520
  ]);
411
521
 
522
+ /**
523
+ * The scripts a gate ends up running: each `pnpm <script>` / `pnpm run <script>` it calls,
524
+ * with every `bkit:gate:*` it chains expanded in place. pnpm's own subcommands and
525
+ * binaries are left out.
526
+ */
527
+ export function gateLeafScripts(
528
+ gate: string,
529
+ declared: Readonly<Record<string, string>>,
530
+ seen: Set<string> = new Set(),
531
+ ): string[] {
532
+ const value = declared[gate];
533
+ if (typeof value !== "string" || seen.has(gate)) return [];
534
+ seen.add(gate);
535
+ const leaves: string[] = [];
536
+ for (const [, called] of value.matchAll(/\bpnpm (?:run )?([\w:-]+)/g)) {
537
+ if (PNPM_NOT_A_SCRIPT.has(called)) continue;
538
+ if (called.startsWith("bkit:gate:")) leaves.push(...gateLeafScripts(called, declared, seen));
539
+ else leaves.push(called);
540
+ }
541
+ return leaves;
542
+ }
543
+
412
544
  /**
413
545
  * Advisories for the `bkit:gate:*` scripts: the scripts a still-default gate
414
546
  * chains that package.json does not declare, the deeper test tiers the repo has
415
- * but no gate runs, and a missing `bkit:test:file`. Judges the scripts as install
547
+ * but no gate runs, a commit gate that repeats the push gate, and a missing
548
+ * `bkit:test:file`. Judges the scripts as install
416
549
  * leaves them (missing gate names at their seeded defaults), so install, `bkit check`
417
550
  * and `bkit upgrade` report the same set. Read-only; an absent or unparseable
418
551
  * package.json yields none.
@@ -461,14 +594,30 @@ export function detectGateAdvisories(cwd: string): PreflightFinding[] {
461
594
  id: "gate-tier-not-wired",
462
595
  severity: "advisory",
463
596
  detect:
464
- "package.json declares deeper test tiers than any `bkit:gate*` script runs, so `/bkit-build` and `/bkit-debug` gate at `bkit:gate:static-unit` and never execute them.",
597
+ "package.json declares deeper test tiers than any `bkit:gate*` script runs, so `/bkit-build`, `/bkit-debug` and the pre-push hook gate at `bkit:gate:static-unit` and never execute them.",
465
598
  action:
466
- "Each workflow runs the DEEPEST gate you declare; an undeclared one is skipped, never guessed. Add the gates you want the agent loop to run:\n\n" +
599
+ "Each workflow runs the DEEPEST gate you declare, and `.husky/pre-push` runs `bkit:gate:static-unit-integration` when it is declared; an undeclared one is skipped, never guessed. Add the gates you want the agent loop to run:\n\n" +
467
600
  unwired.join("\n") +
468
601
  "\n\nOrder matters — each chains the one above it. Omit a level deliberately to keep it CI-only (E2E in the build loop costs a production build on every remediation attempt). `.bkit/templates.md` lists the tool scripts the gates chain.",
469
602
  });
470
603
  }
471
604
 
605
+ // The commit gate is the fast one: a script it shares with the push gate runs on every
606
+ // commit and again on the push that carries it.
607
+ const pushGate = BKIT_PUSH_GATES.find((g) => g in declared);
608
+ const commitCalls = pushGate === undefined ? [] : gateLeafScripts("bkit:gate:format", declared);
609
+ const pushCalls = new Set(pushGate === undefined ? [] : gateLeafScripts(pushGate, declared));
610
+ const repeated = [...new Set(commitCalls.filter((s) => pushCalls.has(s)))].sort();
611
+ if (repeated.length > 0) {
612
+ const names = repeated.map((n) => `\`${n}\``).join(", ");
613
+ findings.push({
614
+ id: "gate-commit-repeats-push",
615
+ severity: "advisory",
616
+ detect: `\`bkit:gate:format\` (pre-commit) runs ${names}, which \`${pushGate}\` (pre-push) runs again.`,
617
+ action: `Drop ${names} from \`bkit:gate:format\`. The commit gate formats staged files and nothing else; every whole-repo check runs once, at pre-push.`,
618
+ });
619
+ }
620
+
472
621
  // /bkit-build records each task's red through this script; without it test-first is
473
622
  // reported as not enforced. bkit cannot seed it: what runs one file is the stack's.
474
623
  if (!(BKIT_TEST_FILE_SCRIPT in declared)) {
@@ -263,6 +263,11 @@ export function renderOpencodeJson(
263
263
  '"github": { "type": "remote", "url": "https://api.githubcopilot.com/mcp/", "oauth": false, "headers": { "Authorization": "Bearer {env:BKIT_GH_TOKEN}", "X-MCP-Toolsets": "context,issues,pull_requests,repos,users,projects,actions" } }';
264
264
  } else if (tracker === "linear") {
265
265
  mcpEntry = '"linear": { "type": "remote", "url": "https://mcp.linear.app/mcp" }';
266
+ } else if (tracker === "jira") {
267
+ // Same "oauth": false reason as github: the API token in the header is the only auth
268
+ // bkit wires, so a bad one fails as a 401, not as an OAuth sign-in prompt.
269
+ mcpEntry =
270
+ '"jira": { "type": "remote", "url": "https://mcp.atlassian.com/v2/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:BKIT_JIRA_API_TOKEN}" } }';
266
271
  } else {
267
272
  mcpEntry = "";
268
273
  }