@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
@@ -15,14 +15,16 @@ export const OPTIN_MODULES = new Set(["cloud", "opencode", "codex", "antigravity
15
15
  // ---------------------------------------------------------------------------
16
16
  /**
17
17
  * Issue-tracker providers supported by `bkit install --tracker=<name>`.
18
- * - `github` — GitHub Issues + Projects v2 (default).
19
- * - `linear` — Linear (opt-in).
20
- * - `none` — no tracker wired; workflows skip tracker calls with one-line log.
18
+ * - `github` — GitHub Issues + Projects v2.
19
+ * - `linear` — Linear.
20
+ * - `jira` — Jira Cloud through the Atlassian Rovo MCP server.
21
+ * - `none` — no tracker wired; workflows skip tracker calls with one-line log (default).
21
22
  *
22
- * Add a new value here when adding a provider section to `.bkit/trackers.md`.
23
- * See `.bkit/trackers.md` § "Adding a tracker (Jira, etc.)" in the Rules block.
23
+ * A new value needs its block in every tracker group of the workflow and prompt
24
+ * sources (`.bkit/trackers.md` § Marker contract) and a branch in
25
+ * `render/trackers.ts`.
24
26
  */
25
- export const ISSUE_TRACKERS = ["github", "linear", "none"];
27
+ export const ISSUE_TRACKERS = ["github", "linear", "jira", "none"];
26
28
  /** Default tracker when consumer manifest has no `bkit.issueTracker` field. */
27
29
  export const DEFAULT_ISSUE_TRACKER = "none";
28
30
  /**
@@ -154,7 +156,9 @@ const CLAUDE_MANIFEST = [
154
156
  // ONE CHAIN. Each gate is the previous gate plus its own tier; the NAME and the
155
157
  // VALUE describe the same sequence. Tier vocabulary is the `bkit-ci.yml` job ids
156
158
  // (bkit-tests-static / -unit / -integration / -e2e / -live). Where a step is not a
157
- // tier (`format`, the ship gate) the name spells out the actual steps.
159
+ // tier (`format`, the ship gate) the name spells out the actual steps. One exception:
160
+ // `min` sits off the chain: the least a push runs, on a push that changes no code
161
+ // (`bkit.minPushPaths`); its steps are whatever that push can still break.
158
162
  //
159
163
  // The consumer owns every value: a turbo monorepo writes `turbo run … --filter`,
160
164
  // a Python repo writes `ruff check && pytest`. bkit never reads a value — only
@@ -178,17 +182,23 @@ const CLAUDE_MANIFEST = [
178
182
  // …-integration-e2e-live) are absent unless the consumer writes them. Each is one line
179
183
  // chaining its parent, e.g.
180
184
  // "bkit:gate:static-unit-integration": "pnpm bkit:gate:static-unit && pnpm test:integration"
181
- // `/bkit-build` and `/bkit-debug` run the DEEPEST gate that exists and record its name.
185
+ // `/bkit-build` and `/bkit-debug` run the DEEPEST gate that exists and record its name;
186
+ // `.husky/pre-push` runs `…-integration` when it exists (BKIT_PUSH_GATES).
182
187
  export const BKIT_GATE_SCRIPTS = {
183
188
  // `.husky/pre-commit`: prettier --write over staged files, and nothing else —
184
189
  // seconds, not minutes. Prose is a whole-repo scan, so it gates at pre-push.
185
190
  "bkit:gate:format": "pnpm lint-staged",
191
+ // `.husky/pre-push` on a min push (every file matches `bkit.minPushPaths`): no code, so
192
+ // no typecheck, lint or tests. Off the chain. Add any test that reads a min-push file.
193
+ "bkit:gate:min": "pnpm format:check && pnpm lint:prose && pnpm slop:delta",
186
194
  // Everything that needs no test runner. Every part has a matching step in the
187
195
  // bkit-tests-static CI job; audits/templates/template-ci-yml.test.ts fails when one is missing.
188
196
  // Callers: build's plan-execute loop between tasks, and the `.husky/pre-push` revert
189
197
  // path.
190
198
  "bkit:gate:static": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm lint:prose && pnpm slop:delta",
191
- // The default local gate: `.husky/pre-push`, build Step 14, the remediates.
199
+ // The default local gate: `.husky/pre-push` (when no `…-integration` gate is declared),
200
+ // build Step 14, the remediates. `pnpm test` is the unit tier only: a test file the
201
+ // integration gate also runs must not match it.
192
202
  "bkit:gate:static-unit": "pnpm bkit:gate:static && pnpm test",
193
203
  // Ship's conflict-resolve, the only caller whose dependency graph may have just
194
204
  // been hand-merged (lockfile conflict) and whose tree no one has ever compiled.
@@ -222,12 +232,22 @@ export const BKIT_DEBUG_GATES = [
222
232
  * Build stops at integration; E2E and live are not in this list.
223
233
  *
224
234
  * Neither entry is seeded: declaring `bkit:gate:static-unit-integration` opts the build
225
- * loop into the integration tier.
235
+ * loop and the pre-push hook into the integration tier.
226
236
  */
227
237
  export const BKIT_BUILD_GATES = [
228
238
  "bkit:gate:static-unit-integration",
229
239
  "bkit:gate:static-unit",
230
240
  ];
241
+ /**
242
+ * What `.husky/pre-push` runs on a full push, in DESCENDING order — first one declared wins.
243
+ *
244
+ * Integration runs on push, never on commit; E2E and live stay in CI. The template hook
245
+ * reads package.json for the first entry itself (it cannot import this list).
246
+ */
247
+ export const BKIT_PUSH_GATES = [
248
+ "bkit:gate:static-unit-integration",
249
+ "bkit:gate:static-unit",
250
+ ];
231
251
  /**
232
252
  * Runs ONE test file — `pnpm bkit:test:file <repo-relative path>` — and writes a JUnit
233
253
  * report to `$BKIT_TEST_REPORT`. `/bkit-build` records each task's red and audits its
@@ -77,7 +77,9 @@ export function runCloudModule(ctx) {
77
77
  CLOUD_WORKFLOW_ADOPT_STEP +
78
78
  " - 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" +
79
79
  " - 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" +
80
- " - 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" +
80
+ " - Give `claude-code-action@v1` ONE claude credential (Settings → Secrets and variables → Actions):\n" +
81
+ " - the `ANTHROPIC_API_KEY` repo secret (job env keeps this vendor name; local `.bkit/.env` stores it as `BKIT_ANTHROPIC_API_KEY`), or\n" +
82
+ " - 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" +
81
83
  " - Label the issue `bkit:auto` before pushing the build commit — without the label the CI auto-route exits no-op.\n\n" +
82
84
  "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" +
83
85
  "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`).",
@@ -9,10 +9,10 @@ import { extractManagedBlock, stripManagedBlock } from "../managed-block.js";
9
9
  import { listFilesRecursive, syncTemplateCopies } from "../template-copies.js";
10
10
  import { PAYLOAD_LINK_RELPATHS, syncPayloadLinks } from "../payload-links.js";
11
11
  import { writeNetworkAllowlist } from "../network-allowlist.js";
12
- import { readJsonFile } from "../../shared/json.js";
12
+ import { parseJson, readJsonFile } from "../../shared/json.js";
13
13
  import { readInstallingVersion } from "../../shared/package-json.js";
14
14
  import { getCoreRoot, getSharedRoot, getBkitDocsRoot, TEMPLATE_COPIES_DIR, } from "../../shared/package-roots.js";
15
- import { getInstallManifest, BKIT_GATE_SCRIPTS, BKIT_OPTIONAL_GATES, BKIT_TEST_FILE_SCRIPT, } from "../manifest.js";
15
+ import { getInstallManifest, BKIT_GATE_SCRIPTS, BKIT_OPTIONAL_GATES, BKIT_PUSH_GATES, BKIT_TEST_FILE_SCRIPT, } from "../manifest.js";
16
16
  export function listMdFiles(dir, prefix) {
17
17
  if (!fs.existsSync(dir))
18
18
  return [];
@@ -315,8 +315,48 @@ export function seedCorePackageJsonScripts(ctx) {
315
315
  written.push("package.json");
316
316
  console.log(`${logPrefix} ${tag}core: package.json scripts added [${gates.added.join(", ")}]`);
317
317
  }
318
+ if (migrateLinearTeamKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
319
+ written.push("package.json");
320
+ }
318
321
  return written;
319
322
  }
323
+ // Migration (up to 5.4.x installs, `docs/migrations.md`): the Linear team lived at
324
+ // `bkit.linearTeam`; it is `bkit.linear.team`, beside the project and state names. An
325
+ // existing `bkit.linear.team` wins over the old key. Returns true when package.json changed.
326
+ export function migrateLinearTeamKey(dryRun, ws, logPrefix) {
327
+ const pkgPath = "package.json";
328
+ if (!fs.existsSync(pkgPath))
329
+ return false;
330
+ const raw = fs.readFileSync(pkgPath, "utf-8");
331
+ const parsed = parseJson(raw);
332
+ if (!parsed.ok)
333
+ return false;
334
+ const pkg = parsed.value;
335
+ const bkit = pkg.bkit;
336
+ if (bkit === null || typeof bkit !== "object" || Array.isArray(bkit))
337
+ return false;
338
+ const cfg = bkit;
339
+ if (!Object.prototype.hasOwnProperty.call(cfg, "linearTeam"))
340
+ return false;
341
+ const old = cfg.linearTeam;
342
+ const linear = cfg.linear !== null && typeof cfg.linear === "object" && !Array.isArray(cfg.linear)
343
+ ? cfg.linear
344
+ : {};
345
+ if (linear.team === undefined && typeof old === "string" && old.trim() !== "")
346
+ linear.team = old;
347
+ delete cfg.linearTeam;
348
+ if (Object.keys(linear).length > 0)
349
+ cfg.linear = linear;
350
+ ws.writes.push({ path: pkgPath, action: "update" });
351
+ if (!dryRun) {
352
+ const indentMatch = raw.match(/\n([ \t]+)"/);
353
+ const indent = indentMatch ? indentMatch[1] : " ";
354
+ const trailingNewline = raw.endsWith("\n") ? "\n" : "";
355
+ fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + trailingNewline, "utf-8");
356
+ }
357
+ console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: moved bkit.linearTeam to bkit.linear.team in package.json`);
358
+ return true;
359
+ }
320
360
  // Tokens that follow `pnpm` in a gate value but are not package.json scripts: the
321
361
  // package manager's own subcommands (`install` in bkit:gate:install-static-unit-build,
322
362
  // `audit` / `outdated` in the bkit:deps:* pair) and node_modules binaries pnpm resolves
@@ -330,10 +370,32 @@ const PNPM_NOT_A_SCRIPT = new Set([
330
370
  "outdated",
331
371
  "lint-staged",
332
372
  ]);
373
+ /**
374
+ * The scripts a gate ends up running: each `pnpm <script>` / `pnpm run <script>` it calls,
375
+ * with every `bkit:gate:*` it chains expanded in place. pnpm's own subcommands and
376
+ * binaries are left out.
377
+ */
378
+ export function gateLeafScripts(gate, declared, seen = new Set()) {
379
+ const value = declared[gate];
380
+ if (typeof value !== "string" || seen.has(gate))
381
+ return [];
382
+ seen.add(gate);
383
+ const leaves = [];
384
+ for (const [, called] of value.matchAll(/\bpnpm (?:run )?([\w:-]+)/g)) {
385
+ if (PNPM_NOT_A_SCRIPT.has(called))
386
+ continue;
387
+ if (called.startsWith("bkit:gate:"))
388
+ leaves.push(...gateLeafScripts(called, declared, seen));
389
+ else
390
+ leaves.push(called);
391
+ }
392
+ return leaves;
393
+ }
333
394
  /**
334
395
  * Advisories for the `bkit:gate:*` scripts: the scripts a still-default gate
335
396
  * chains that package.json does not declare, the deeper test tiers the repo has
336
- * but no gate runs, and a missing `bkit:test:file`. Judges the scripts as install
397
+ * but no gate runs, a commit gate that repeats the push gate, and a missing
398
+ * `bkit:test:file`. Judges the scripts as install
337
399
  * leaves them (missing gate names at their seeded defaults), so install, `bkit check`
338
400
  * and `bkit upgrade` report the same set. Read-only; an absent or unparseable
339
401
  * package.json yields none.
@@ -384,12 +446,27 @@ export function detectGateAdvisories(cwd) {
384
446
  findings.push({
385
447
  id: "gate-tier-not-wired",
386
448
  severity: "advisory",
387
- detect: "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.",
388
- action: "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" +
449
+ detect: "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.",
450
+ action: "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" +
389
451
  unwired.join("\n") +
390
452
  "\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.",
391
453
  });
392
454
  }
455
+ // The commit gate is the fast one: a script it shares with the push gate runs on every
456
+ // commit and again on the push that carries it.
457
+ const pushGate = BKIT_PUSH_GATES.find((g) => g in declared);
458
+ const commitCalls = pushGate === undefined ? [] : gateLeafScripts("bkit:gate:format", declared);
459
+ const pushCalls = new Set(pushGate === undefined ? [] : gateLeafScripts(pushGate, declared));
460
+ const repeated = [...new Set(commitCalls.filter((s) => pushCalls.has(s)))].sort();
461
+ if (repeated.length > 0) {
462
+ const names = repeated.map((n) => `\`${n}\``).join(", ");
463
+ findings.push({
464
+ id: "gate-commit-repeats-push",
465
+ severity: "advisory",
466
+ detect: `\`bkit:gate:format\` (pre-commit) runs ${names}, which \`${pushGate}\` (pre-push) runs again.`,
467
+ 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.`,
468
+ });
469
+ }
393
470
  // /bkit-build records each task's red through this script; without it test-first is
394
471
  // reported as not enforced. bkit cannot seed it: what runs one file is the stack's.
395
472
  if (!(BKIT_TEST_FILE_SCRIPT in declared)) {
@@ -212,6 +212,12 @@ export function renderOpencodeJson(templatePath, tracker, provider, cwd = proces
212
212
  else if (tracker === "linear") {
213
213
  mcpEntry = '"linear": { "type": "remote", "url": "https://mcp.linear.app/mcp" }';
214
214
  }
215
+ else if (tracker === "jira") {
216
+ // Same "oauth": false reason as github: the API token in the header is the only auth
217
+ // bkit wires, so a bad one fails as a 401, not as an OAuth sign-in prompt.
218
+ mcpEntry =
219
+ '"jira": { "type": "remote", "url": "https://mcp.atlassian.com/v2/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:BKIT_JIRA_API_TOKEN}" } }';
220
+ }
215
221
  else {
216
222
  mcpEntry = "";
217
223
  }
@@ -238,6 +238,24 @@ export function writeTier2JsonContained(srcPath, dstPath, dryRun, ws) {
238
238
  export function ensureDir(dir) {
239
239
  fs.mkdirSync(dir, { recursive: true });
240
240
  }
241
+ /**
242
+ * Give an existing `dstPath` the executable bits `srcPath` carries. Hosts run some hooks
243
+ * directly (Cursor's `bkit-preflight.sh`), so a lost bit is drift: recorded in `ws` (a dry
244
+ * run included, so `bkit check` fails) and restored on a real run. No-op on Windows.
245
+ */
246
+ export function restoreExecBits(srcPath, dstPath, dryRun, ws) {
247
+ if (process.platform === "win32" || !fs.existsSync(dstPath))
248
+ return;
249
+ const execBits = fs.statSync(srcPath).mode & 0o111;
250
+ const dstMode = fs.statSync(dstPath).mode;
251
+ if ((dstMode & execBits) === execBits)
252
+ return;
253
+ if (!dryRun)
254
+ fs.chmodSync(dstPath, (dstMode | execBits) & 0o7777);
255
+ if (!ws.writes.some((w) => w.path === dstPath)) {
256
+ ws.writes.push({ path: dstPath, action: "update" });
257
+ }
258
+ }
241
259
  // ---------------------------------------------------------------------------
242
260
  // fully-managed format — idempotent rewrite of whole file after token substitution
243
261
  //
@@ -249,8 +267,10 @@ export function writeTier1(srcPath, dstPath, tokens, dryRun, ws) {
249
267
  const srcContent = applyTokens(srcRaw, tokens);
250
268
  if (fs.existsSync(dstPath)) {
251
269
  const existing = fs.readFileSync(dstPath, "utf-8");
252
- if (existing === srcContent)
253
- return; // identical — no-op
270
+ if (existing === srcContent) {
271
+ restoreExecBits(srcPath, dstPath, dryRun, ws);
272
+ return;
273
+ }
254
274
  }
255
275
  ensureDir(path.dirname(dstPath));
256
276
  if (!dryRun) {
@@ -317,6 +337,10 @@ function hasRetiredDriver(dstPath, content, markerStyle) {
317
337
  return false;
318
338
  }
319
339
  export function writeTier2(srcPath, dstPath, tokens, markerStyle, dryRun, ws) {
340
+ writeTier2Content(srcPath, dstPath, tokens, markerStyle, dryRun, ws);
341
+ restoreExecBits(srcPath, dstPath, dryRun, ws);
342
+ }
343
+ function writeTier2Content(srcPath, dstPath, tokens, markerStyle, dryRun, ws) {
320
344
  const srcRaw = readTemplate(srcPath);
321
345
  // A retired, unedited bkit driver is bkit's code, not the consumer's: replace the
322
346
  // whole file so the new driver ships with the new block.
@@ -3,15 +3,16 @@
3
3
  // `.bkit/workflows/bkit-*.md` to host commands and `.bkit/prompts/bkit-*.md` to
4
4
  // host agents.
5
5
  //
6
- // Inline model (no trackers.md substitution): every tracker call site carries the
7
- // `github` and `linear` variants inline as a consecutive pair. The installer keeps
8
- // the block matching the chosen tracker and drops the other. Two boolean
6
+ // Inline model (no trackers.md substitution): every tracker call site carries one
7
+ // variant per tracker inline as a consecutive group, in the fixed order `github`,
8
+ // `linear`, `jira`. The installer keeps the block matching the chosen tracker and
9
+ // drops the others. Two boolean
9
10
  // conditional dialects gate tracker-agnostic content:
10
11
  //
11
12
  // <!-- bkit:tracker true start/end --> kept when a tracker IS connected; removed under none
12
13
  // <!-- bkit:tracker false start/end --> kept ONLY under none; removed when wired
13
14
  //
14
- // Under `none` a pair collapses to its trailing `false` block if present (the
15
+ // Under `none` a group collapses to its trailing `false` block if present (the
15
16
  // substantive no-tracker behaviour — e.g. `issue-id-extraction`, `fid-format`,
16
17
  // `pr-body-marker`), otherwise to one generic skip message. There is no separate
17
18
  // `none` marker — no-tracker content is always `false`.
@@ -20,7 +21,7 @@
20
21
  // ---------------------------------------------------------------------------
21
22
  // Markers
22
23
  // ---------------------------------------------------------------------------
23
- /** Generic message rendered in place of a github/linear pair when no tracker is wired. */
24
+ /** Generic message rendered in place of a tracker group when no tracker is wired. */
24
25
  const NONE_STUB = "_No tracker connected, skip step._";
25
26
  /**
26
27
  * Marker regex source. An optional `# ` prefix belongs to the marker: inside YAML
@@ -36,12 +37,14 @@ function block(name) {
36
37
  return `${marker(name, "start")}([\\s\\S]*?)${marker(name, "end")}`;
37
38
  }
38
39
  /**
39
- * Per-tracker group: a consecutive `github` → `linear` pair, each
40
+ * Per-tracker group: consecutive `github` → `linear` → `jira` blocks, each
40
41
  * `<!-- bkit:tracker {name} start -->` … `<!-- bkit:tracker {name} end -->`,
41
- * with an OPTIONAL trailing `false` block. The whitespace BEFORE the optional
42
- * `false` block lives INSIDE the optional group (`(?:\s*<false>)?`), so when no
43
- * `false` follows the pair, the trailing newline + indent are left untouched —
44
- * otherwise content immediately after the pair would jam onto the kept body. A
42
+ * with an OPTIONAL trailing `false` block. The `jira` block is optional to the
43
+ * match: a group without one resolves for github, linear and none, and is left
44
+ * whole under jira so its markers surface as orphans. The whitespace BEFORE each
45
+ * optional block lives INSIDE its optional group (`(?:\s*<false>)?`), so when no
46
+ * block follows, the trailing newline + indent are left untouched — otherwise
47
+ * content immediately after the group would jam onto the kept body. A
45
48
  * list-number prefix (`3. `) precedes the first marker and is left untouched, so
46
49
  * the kept body / none stub attaches to it cleanly.
47
50
  *
@@ -50,7 +53,14 @@ function block(name) {
50
53
  * `pr-body-marker`), use its body; otherwise emit the generic skip message.
51
54
  * (Standalone `false` blocks not attached to a pair are handled in pass 2.)
52
55
  */
53
- const PAIR_RE = new RegExp(block("github") + "\\s*" + block("linear") + "(?:\\s*" + block("false") + ")?", "g");
56
+ const GROUP_RE = new RegExp(block("github") +
57
+ "\\s*" +
58
+ block("linear") +
59
+ "(?:\\s*" +
60
+ block("jira") +
61
+ ")?(?:\\s*" +
62
+ block("false") +
63
+ ")?", "g");
54
64
  /** Conditional-keep block, KEEP form (markers stripped, content trimmed in place). */
55
65
  function condKeepRe(name) {
56
66
  return new RegExp(block(name), "g");
@@ -59,9 +69,9 @@ function condKeepRe(name) {
59
69
  function condDropRe(name) {
60
70
  return new RegExp(`\\n?[ \\t]*${block(name)}`, "g");
61
71
  }
62
- // Any tracker marker surviving resolution is an orphan (lone github/linear, or
72
+ // Any tracker marker surviving resolution is an orphan (an incomplete group, or
63
73
  // unbalanced true/false).
64
- const ORPHAN_RE = new RegExp(marker("(github|linear|true|false)", "(?:start|end)"), "g");
74
+ const ORPHAN_RE = new RegExp(marker("(github|linear|jira|true|false)", "(?:start|end)"), "g");
65
75
  /**
66
76
  * When keeping in-place content, drop the newline (and its indentation)
67
77
  * immediately after `start -->` and immediately before the `end` marker, so the
@@ -78,10 +88,10 @@ function trimKeptContent(s) {
78
88
  /**
79
89
  * Resolve tracker blocks in a workflow source file for the chosen tracker.
80
90
  *
81
- * Pass 1 collapses each github/linear pair to the chosen tracker's body, or — for
91
+ * Pass 1 collapses each tracker group to the chosen tracker's body, or — for
82
92
  * `none` — to the generic skip message. Pass 2 resolves the `true`/`false`
83
93
  * conditional blocks (kept when their condition matches the chosen tracker,
84
- * removed otherwise) — run AFTER pass 1 so pairs nested inside a kept conditional
94
+ * removed otherwise) — run AFTER pass 1 so groups nested inside a kept conditional
85
95
  * are resolved first. Mirror output is clean — no markers remain.
86
96
  *
87
97
  * Always operates on workflow SOURCE (which has markers). Mirror output is
@@ -89,19 +99,23 @@ function trimKeptContent(s) {
89
99
  */
90
100
  export function substituteWorkflow(workflowContent, tracker) {
91
101
  const wired = tracker !== "none";
92
- // Pass 1: github/linear pairs → chosen tracker's body; none → the pair's
93
- // trailing `false` block if present, else the generic skip message.
102
+ // Pass 1: tracker groups → chosen tracker's body; none → the group's trailing
103
+ // `false` block if present, else the generic skip message.
94
104
  let pairs = 0;
95
- let output = workflowContent.replace(PAIR_RE, (_match, gh, ln, falseBody) => {
105
+ let output = workflowContent.replace(GROUP_RE, (match, gh, ln, jira, falseBody) => {
106
+ if (tracker === "jira" && jira === undefined)
107
+ return match;
96
108
  pairs++;
97
109
  if (tracker === "github")
98
110
  return trimKeptContent(gh);
99
111
  if (tracker === "linear")
100
112
  return trimKeptContent(ln);
113
+ if (tracker === "jira")
114
+ return trimKeptContent(jira);
101
115
  return falseBody !== undefined ? trimKeptContent(falseBody) : NONE_STUB;
102
116
  });
103
117
  // Pass 2: standalone conditional `true`/`false` blocks (any `false` attached to
104
- // a pair was already consumed in pass 1).
118
+ // a group was already consumed in pass 1).
105
119
  let conditionals = 0;
106
120
  for (const name of ["true", "false"]) {
107
121
  const active = name === "true" ? wired : !wired;
@@ -122,7 +136,7 @@ export function substituteWorkflow(workflowContent, tracker) {
122
136
  }
123
137
  /**
124
138
  * Find tracker markers that didn't participate in a successful resolution — a
125
- * lone github/linear block (not part of a complete pair) or an unbalanced
139
+ * block outside a complete group, a group lacking the chosen tracker, or an unbalanced
126
140
  * true/false pair.
127
141
  */
128
142
  function findOrphanMarkers(content) {
@@ -109,6 +109,12 @@ export const BKIT_EGRESS_SOURCES = [
109
109
  hosts: ["mcp.linear.app", "api.linear.app"],
110
110
  bases: ["linear.app"],
111
111
  },
112
+ {
113
+ id: "mcp-jira",
114
+ kind: "tracker-mcp",
115
+ hosts: ["mcp.atlassian.com"],
116
+ bases: ["atlassian.com"],
117
+ },
112
118
  {
113
119
  id: "agent-claude",
114
120
  kind: "agent-host",
@@ -12,8 +12,14 @@ export const CONFIG_DEFAULTS = {
12
12
  worktreeInstall: true,
13
13
  diskMinFreeGb: 40,
14
14
  issueTracker: DEFAULT_ISSUE_TRACKER,
15
+ // `started` is a state type every Linear team has; In Review is a name a default team lacks.
16
+ linear: { team: null, project: null, progress: "started", review: "In Review" },
17
+ jira: { site: null, project: null, progress: "In Progress", review: "In Review" },
15
18
  githubProject: null,
16
19
  shipGateRequiredLanes: [],
20
+ // What bkit's workflows write: plan / design / build logs and the ledgers. Never
21
+ // `docs/**`: a project doc can be a test's input, so a docs edit can red a test.
22
+ minPushPaths: ["docs/plans/**", "docs/*.jsonl", ".bkit/*.jsonl"],
17
23
  opencodeProvider: null,
18
24
  opencodeProviders: [],
19
25
  cloudAgents: DEFAULT_CLOUD_AGENTS,
@@ -22,6 +28,15 @@ export const CONFIG_DEFAULTS = {
22
28
  cloudAgentsExplicit: false,
23
29
  };
24
30
  const nonEmptyString = (v) => typeof v === "string" && v.trim() !== "";
31
+ const record = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
32
+ const optionalString = (v) => (nonEmptyString(v) ? v.trim() : null);
33
+ /** Each moment's state from `raw`, else the default for that moment. */
34
+ function trackerStates(raw, defaults) {
35
+ return {
36
+ progress: nonEmptyString(raw.progress) ? raw.progress.trim() : defaults.progress,
37
+ review: nonEmptyString(raw.review) ? raw.review.trim() : defaults.review,
38
+ };
39
+ }
25
40
  /**
26
41
  * Read `package.json` `bkit` from `root` (the main checkout). A missing file,
27
42
  * missing key, or wrongly typed value falls back to the default for that key.
@@ -35,8 +50,11 @@ export function readBkitConfig(root) {
35
50
  const minFreeGb = (bkit.disk ?? {}).minFreeGb;
36
51
  const project = bkit.githubProject;
37
52
  const lanes = bkit.shipGateRequiredLanes;
53
+ const book = bkit.minPushPaths;
38
54
  const provider = bkit.opencodeProvider;
39
55
  const providers = bkit.opencodeProviders;
56
+ const linear = record(bkit.linear);
57
+ const jira = record(bkit.jira);
40
58
  return {
41
59
  ciWorkflow: nonEmptyString(bkit.ciWorkflow) ? bkit.ciWorkflow : CONFIG_DEFAULTS.ciWorkflow,
42
60
  capstoneJob: nonEmptyString(bkit.capstoneJob) ? bkit.capstoneJob : CONFIG_DEFAULTS.capstoneJob,
@@ -48,12 +66,26 @@ export function readBkitConfig(root) {
48
66
  ? minFreeGb
49
67
  : CONFIG_DEFAULTS.diskMinFreeGb,
50
68
  issueTracker: parseIssueTracker(bkit.issueTracker) ?? CONFIG_DEFAULTS.issueTracker,
69
+ linear: {
70
+ team: optionalString(linear.team),
71
+ project: optionalString(linear.project),
72
+ ...trackerStates(linear, CONFIG_DEFAULTS.linear),
73
+ },
74
+ jira: {
75
+ site: nonEmptyString(jira.site) ? jira.site.trim().replace(/\/+$/, "") : null,
76
+ project: optionalString(jira.project),
77
+ ...trackerStates(jira, CONFIG_DEFAULTS.jira),
78
+ },
51
79
  githubProject: project === false
52
80
  ? false
53
81
  : project !== null && typeof project === "object" && !Array.isArray(project)
54
82
  ? project
55
83
  : null,
56
84
  shipGateRequiredLanes: Array.isArray(lanes) ? lanes.filter(nonEmptyString) : [],
85
+ // An explicit [] is kept: it switches the min push off.
86
+ minPushPaths: Array.isArray(book)
87
+ ? book.filter(nonEmptyString)
88
+ : [...CONFIG_DEFAULTS.minPushPaths],
57
89
  opencodeProvider: typeof provider === "string" && isOpencodeProvider(provider) ? provider : null,
58
90
  opencodeProviders: Array.isArray(providers)
59
91
  ? providers.filter((v) => typeof v === "string" && isOpencodeProvider(v))
@@ -64,3 +96,10 @@ export function readBkitConfig(root) {
64
96
  cloudAgentsExplicit: bkit.cloudAgents !== undefined,
65
97
  };
66
98
  }
99
+ export function trackerScope(cfg) {
100
+ if (cfg.issueTracker === "linear")
101
+ return { trackerTeam: cfg.linear.team, trackerProject: cfg.linear.project, trackerSite: null };
102
+ if (cfg.issueTracker === "jira")
103
+ return { trackerTeam: null, trackerProject: cfg.jira.project, trackerSite: cfg.jira.site };
104
+ return { trackerTeam: null, trackerProject: null, trackerSite: null };
105
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cbartens/bkit",
3
- "version": "5.4.0",
3
+ "version": "5.5.0",
4
4
  "private": false,
5
5
  "description": "From vibe coding to production code. A senior engineering team's process, ready-made: AI agents design, plan, build, review, fix and ship your features on Claude Code, Cursor, Codex, Google Antigravity and opencode.",
6
6
  "keywords": [
@@ -54,8 +54,10 @@
54
54
  "license": "MIT",
55
55
  "scripts": {
56
56
  "bkit:gate:format": "pnpm lint-staged",
57
+ "bkit:gate:min": "pnpm format:check && pnpm format:tables:check && pnpm lint:prose && pnpm slop:delta && vitest run .bkit/core/engine/audits/repo/ledger-integrity.test.ts",
57
58
  "bkit:gate:static": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm format:tables:check && pnpm lint:prose && pnpm slop:delta",
58
- "bkit:gate:static-unit": "pnpm bkit:gate:static && pnpm test && pnpm test:coverage:unit && pnpm bkit:test:bats",
59
+ "bkit:gate:static-unit": "pnpm bkit:gate:static && pnpm test:coverage:unit && pnpm bkit:test:bats",
60
+ "bkit:gate:static-unit-integration": "pnpm bkit:gate:static-unit && pnpm test:integration",
59
61
  "bkit:gate:install-static-unit-build": "pnpm install --frozen-lockfile && pnpm bkit:gate:static-unit && pnpm build",
60
62
  "bkit:deps:outdated": "pnpm outdated",
61
63
  "bkit:deps:audit": "pnpm audit",
@@ -73,6 +75,7 @@
73
75
  "slop:delta": "bkit ci slop",
74
76
  "bkit:lint:workflows": "bash -c 'if command -v actionlint >/dev/null 2>&1; then actionlint; else echo \"[bkit] actionlint missing — skipping workflow lint (install actionlint to enable)\"; fi'",
75
77
  "test": "vitest run",
78
+ "test:integration": "vitest run integration.test",
76
79
  "test:coverage:unit": "vitest run -c vitest.unit.config.ts --coverage --coverage.reportsDirectory=coverage/unit --exclude '**/*.integration.test.ts' --coverage.include='.bkit/core/engine/{cli,commands/analysis,install/cloud-env,commands/comply,commands/harvest,commands/install/install,commands/launch,install/manifest,install/managed-block,shared/package-roots,shared/protected-paths,checks/after/index,checks/after/auth,checks/after/ci-yml,checks/after/github,checks/after/managed,checks/after/tools,checks/after/suppression,checks/before/index,checks/before/context-fetch,checks/before/env,checks/before/files,checks/before/mcp,checks/before/repo,checks/before/version,ledgers/status,ledgers/telemetry,install/write,install/placeholders,install/template-copies,render/trackers,render/hosts,render/models,commands/install/uninstall,commands/install/upgrade,install/version-file,tools/wording}.ts' --coverage.include='.bkit/core/engine/commands/**/*.ts' --coverage.include='.bkit/core/engine/shared/{settings,package-json,package-manager,timeouts}.ts'",
77
80
  "bkit:test:bats": "pnpm exec bats tests/*.bats",
78
81
  "build": "tsc && chmod +x dist/cli.js",
@@ -122,6 +125,12 @@
122
125
  "opencode-go",
123
126
  "openrouter"
124
127
  ],
128
+ "minPushPaths": [
129
+ "docs/**",
130
+ ".bkit/*.jsonl",
131
+ "CHANGELOG.md",
132
+ "README.md"
133
+ ],
125
134
  "capstoneJob": "bkit-tests-check",
126
135
  "ciWorkflow": "bkit-ci.yml",
127
136
  "roadmapNext": 25