@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
@@ -17,7 +17,7 @@ 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
22
  import {
23
23
  getCoreRoot,
@@ -29,6 +29,7 @@ import {
29
29
  getInstallManifest,
30
30
  BKIT_GATE_SCRIPTS,
31
31
  BKIT_OPTIONAL_GATES,
32
+ BKIT_PUSH_GATES,
32
33
  BKIT_TEST_FILE_SCRIPT,
33
34
  } from "../manifest.js";
34
35
  import type { ModuleContext } from "./index.js";
@@ -392,9 +393,47 @@ export function seedCorePackageJsonScripts(
392
393
  written.push("package.json");
393
394
  console.log(`${logPrefix} ${tag}core: package.json scripts added [${gates.added.join(", ")}]`);
394
395
  }
396
+ if (migrateLinearTeamKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
397
+ written.push("package.json");
398
+ }
395
399
  return written;
396
400
  }
397
401
 
402
+ // Migration (up to 5.4.x installs, `docs/migrations.md`): the Linear team lived at
403
+ // `bkit.linearTeam`; it is `bkit.linear.team`, beside the project and state names. An
404
+ // existing `bkit.linear.team` wins over the old key. Returns true when package.json changed.
405
+ export function migrateLinearTeamKey(dryRun: boolean, ws: WriteSet, logPrefix: string): boolean {
406
+ const pkgPath = "package.json";
407
+ if (!fs.existsSync(pkgPath)) return false;
408
+ const raw = fs.readFileSync(pkgPath, "utf-8");
409
+ const parsed = parseJson(raw);
410
+ if (!parsed.ok) return false;
411
+ const pkg = parsed.value as Record<string, unknown>;
412
+ const bkit = pkg.bkit;
413
+ if (bkit === null || typeof bkit !== "object" || Array.isArray(bkit)) return false;
414
+ const cfg = bkit as Record<string, unknown>;
415
+ if (!Object.prototype.hasOwnProperty.call(cfg, "linearTeam")) return false;
416
+ const old = cfg.linearTeam;
417
+ const linear =
418
+ cfg.linear !== null && typeof cfg.linear === "object" && !Array.isArray(cfg.linear)
419
+ ? (cfg.linear as Record<string, unknown>)
420
+ : {};
421
+ if (linear.team === undefined && typeof old === "string" && old.trim() !== "") linear.team = old;
422
+ delete cfg.linearTeam;
423
+ if (Object.keys(linear).length > 0) cfg.linear = linear;
424
+ ws.writes.push({ path: pkgPath, action: "update" });
425
+ if (!dryRun) {
426
+ const indentMatch = raw.match(/\n([ \t]+)"/);
427
+ const indent = indentMatch ? indentMatch[1] : " ";
428
+ const trailingNewline = raw.endsWith("\n") ? "\n" : "";
429
+ fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + trailingNewline, "utf-8");
430
+ }
431
+ console.log(
432
+ `${logPrefix} ${dryRun ? "[dry-run] " : ""}core: moved bkit.linearTeam to bkit.linear.team in package.json`,
433
+ );
434
+ return true;
435
+ }
436
+
398
437
  // Tokens that follow `pnpm` in a gate value but are not package.json scripts: the
399
438
  // package manager's own subcommands (`install` in bkit:gate:install-static-unit-build,
400
439
  // `audit` / `outdated` in the bkit:deps:* pair) and node_modules binaries pnpm resolves
@@ -409,10 +448,33 @@ const PNPM_NOT_A_SCRIPT = new Set([
409
448
  "lint-staged",
410
449
  ]);
411
450
 
451
+ /**
452
+ * The scripts a gate ends up running: each `pnpm <script>` / `pnpm run <script>` it calls,
453
+ * with every `bkit:gate:*` it chains expanded in place. pnpm's own subcommands and
454
+ * binaries are left out.
455
+ */
456
+ export function gateLeafScripts(
457
+ gate: string,
458
+ declared: Readonly<Record<string, string>>,
459
+ seen: Set<string> = new Set(),
460
+ ): string[] {
461
+ const value = declared[gate];
462
+ if (typeof value !== "string" || seen.has(gate)) return [];
463
+ seen.add(gate);
464
+ const leaves: string[] = [];
465
+ for (const [, called] of value.matchAll(/\bpnpm (?:run )?([\w:-]+)/g)) {
466
+ if (PNPM_NOT_A_SCRIPT.has(called)) continue;
467
+ if (called.startsWith("bkit:gate:")) leaves.push(...gateLeafScripts(called, declared, seen));
468
+ else leaves.push(called);
469
+ }
470
+ return leaves;
471
+ }
472
+
412
473
  /**
413
474
  * Advisories for the `bkit:gate:*` scripts: the scripts a still-default gate
414
475
  * 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
476
+ * but no gate runs, a commit gate that repeats the push gate, and a missing
477
+ * `bkit:test:file`. Judges the scripts as install
416
478
  * leaves them (missing gate names at their seeded defaults), so install, `bkit check`
417
479
  * and `bkit upgrade` report the same set. Read-only; an absent or unparseable
418
480
  * package.json yields none.
@@ -461,14 +523,30 @@ export function detectGateAdvisories(cwd: string): PreflightFinding[] {
461
523
  id: "gate-tier-not-wired",
462
524
  severity: "advisory",
463
525
  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.",
526
+ "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
527
  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" +
528
+ "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
529
  unwired.join("\n") +
468
530
  "\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
531
  });
470
532
  }
471
533
 
534
+ // The commit gate is the fast one: a script it shares with the push gate runs on every
535
+ // commit and again on the push that carries it.
536
+ const pushGate = BKIT_PUSH_GATES.find((g) => g in declared);
537
+ const commitCalls = pushGate === undefined ? [] : gateLeafScripts("bkit:gate:format", declared);
538
+ const pushCalls = new Set(pushGate === undefined ? [] : gateLeafScripts(pushGate, declared));
539
+ const repeated = [...new Set(commitCalls.filter((s) => pushCalls.has(s)))].sort();
540
+ if (repeated.length > 0) {
541
+ const names = repeated.map((n) => `\`${n}\``).join(", ");
542
+ findings.push({
543
+ id: "gate-commit-repeats-push",
544
+ severity: "advisory",
545
+ detect: `\`bkit:gate:format\` (pre-commit) runs ${names}, which \`${pushGate}\` (pre-push) runs again.`,
546
+ 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.`,
547
+ });
548
+ }
549
+
472
550
  // /bkit-build records each task's red through this script; without it test-first is
473
551
  // reported as not enforced. bkit cannot seed it: what runs one file is the stack's.
474
552
  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
  }
@@ -319,6 +319,27 @@ export function ensureDir(dir: string): void {
319
319
  fs.mkdirSync(dir, { recursive: true });
320
320
  }
321
321
 
322
+ /**
323
+ * Give an existing `dstPath` the executable bits `srcPath` carries. Hosts run some hooks
324
+ * directly (Cursor's `bkit-preflight.sh`), so a lost bit is drift: recorded in `ws` (a dry
325
+ * run included, so `bkit check` fails) and restored on a real run. No-op on Windows.
326
+ */
327
+ export function restoreExecBits(
328
+ srcPath: string,
329
+ dstPath: string,
330
+ dryRun: boolean,
331
+ ws: WriteSet,
332
+ ): void {
333
+ if (process.platform === "win32" || !fs.existsSync(dstPath)) return;
334
+ const execBits = fs.statSync(srcPath).mode & 0o111;
335
+ const dstMode = fs.statSync(dstPath).mode;
336
+ if ((dstMode & execBits) === execBits) return;
337
+ if (!dryRun) fs.chmodSync(dstPath, (dstMode | execBits) & 0o7777);
338
+ if (!ws.writes.some((w) => w.path === dstPath)) {
339
+ ws.writes.push({ path: dstPath, action: "update" });
340
+ }
341
+ }
342
+
322
343
  // ---------------------------------------------------------------------------
323
344
  // fully-managed format — idempotent rewrite of whole file after token substitution
324
345
  //
@@ -338,7 +359,10 @@ export function writeTier1(
338
359
 
339
360
  if (fs.existsSync(dstPath)) {
340
361
  const existing = fs.readFileSync(dstPath, "utf-8");
341
- if (existing === srcContent) return; // identical — no-op
362
+ if (existing === srcContent) {
363
+ restoreExecBits(srcPath, dstPath, dryRun, ws);
364
+ return;
365
+ }
342
366
  }
343
367
 
344
368
  ensureDir(path.dirname(dstPath));
@@ -418,6 +442,18 @@ export function writeTier2(
418
442
  markerStyle: MarkerStyle,
419
443
  dryRun: boolean,
420
444
  ws: WriteSet,
445
+ ): void {
446
+ writeTier2Content(srcPath, dstPath, tokens, markerStyle, dryRun, ws);
447
+ restoreExecBits(srcPath, dstPath, dryRun, ws);
448
+ }
449
+
450
+ function writeTier2Content(
451
+ srcPath: string,
452
+ dstPath: string,
453
+ tokens: TokenMap,
454
+ markerStyle: MarkerStyle,
455
+ dryRun: boolean,
456
+ ws: WriteSet,
421
457
  ): void {
422
458
  const srcRaw = readTemplate(srcPath);
423
459
 
@@ -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`.
@@ -27,7 +28,7 @@ import type { IssueTracker } from "../install/manifest.js";
27
28
  export interface SubstituteResult {
28
29
  /** Workflow content with tracker blocks resolved for the chosen tracker. */
29
30
  output: string;
30
- /** Number of github/linear pairs resolved (to a body or the none stub). */
31
+ /** Number of tracker groups resolved (to a body or the none stub). */
31
32
  pairs: number;
32
33
  /** Number of `true`/`false` conditional blocks resolved (kept or removed). */
33
34
  conditionals: number;
@@ -39,7 +40,7 @@ export interface SubstituteResult {
39
40
  // Markers
40
41
  // ---------------------------------------------------------------------------
41
42
 
42
- /** Generic message rendered in place of a github/linear pair when no tracker is wired. */
43
+ /** Generic message rendered in place of a tracker group when no tracker is wired. */
43
44
  const NONE_STUB = "_No tracker connected, skip step._";
44
45
 
45
46
  /**
@@ -57,12 +58,14 @@ function block(name: string): string {
57
58
  }
58
59
 
59
60
  /**
60
- * Per-tracker group: a consecutive `github` → `linear` pair, each
61
+ * Per-tracker group: consecutive `github` → `linear` → `jira` blocks, each
61
62
  * `<!-- bkit:tracker {name} start -->` … `<!-- bkit:tracker {name} end -->`,
62
- * with an OPTIONAL trailing `false` block. The whitespace BEFORE the optional
63
- * `false` block lives INSIDE the optional group (`(?:\s*<false>)?`), so when no
64
- * `false` follows the pair, the trailing newline + indent are left untouched —
65
- * otherwise content immediately after the pair would jam onto the kept body. A
63
+ * with an OPTIONAL trailing `false` block. The `jira` block is optional to the
64
+ * match: a group without one resolves for github, linear and none, and is left
65
+ * whole under jira so its markers surface as orphans. The whitespace BEFORE each
66
+ * optional block lives INSIDE its optional group (`(?:\s*<false>)?`), so when no
67
+ * block follows, the trailing newline + indent are left untouched — otherwise
68
+ * content immediately after the group would jam onto the kept body. A
66
69
  * list-number prefix (`3. `) precedes the first marker and is left untouched, so
67
70
  * the kept body / none stub attaches to it cleanly.
68
71
  *
@@ -71,8 +74,15 @@ function block(name: string): string {
71
74
  * `pr-body-marker`), use its body; otherwise emit the generic skip message.
72
75
  * (Standalone `false` blocks not attached to a pair are handled in pass 2.)
73
76
  */
74
- const PAIR_RE = new RegExp(
75
- block("github") + "\\s*" + block("linear") + "(?:\\s*" + block("false") + ")?",
77
+ const GROUP_RE = new RegExp(
78
+ block("github") +
79
+ "\\s*" +
80
+ block("linear") +
81
+ "(?:\\s*" +
82
+ block("jira") +
83
+ ")?(?:\\s*" +
84
+ block("false") +
85
+ ")?",
76
86
  "g",
77
87
  );
78
88
 
@@ -85,9 +95,9 @@ function condDropRe(name: "true" | "false"): RegExp {
85
95
  return new RegExp(`\\n?[ \\t]*${block(name)}`, "g");
86
96
  }
87
97
 
88
- // Any tracker marker surviving resolution is an orphan (lone github/linear, or
98
+ // Any tracker marker surviving resolution is an orphan (an incomplete group, or
89
99
  // unbalanced true/false).
90
- const ORPHAN_RE = new RegExp(marker("(github|linear|true|false)", "(?:start|end)"), "g");
100
+ const ORPHAN_RE = new RegExp(marker("(github|linear|jira|true|false)", "(?:start|end)"), "g");
91
101
 
92
102
  /**
93
103
  * When keeping in-place content, drop the newline (and its indentation)
@@ -107,10 +117,10 @@ function trimKeptContent(s: string): string {
107
117
  /**
108
118
  * Resolve tracker blocks in a workflow source file for the chosen tracker.
109
119
  *
110
- * Pass 1 collapses each github/linear pair to the chosen tracker's body, or — for
120
+ * Pass 1 collapses each tracker group to the chosen tracker's body, or — for
111
121
  * `none` — to the generic skip message. Pass 2 resolves the `true`/`false`
112
122
  * conditional blocks (kept when their condition matches the chosen tracker,
113
- * removed otherwise) — run AFTER pass 1 so pairs nested inside a kept conditional
123
+ * removed otherwise) — run AFTER pass 1 so groups nested inside a kept conditional
114
124
  * are resolved first. Mirror output is clean — no markers remain.
115
125
  *
116
126
  * Always operates on workflow SOURCE (which has markers). Mirror output is
@@ -122,21 +132,23 @@ export function substituteWorkflow(
122
132
  ): SubstituteResult {
123
133
  const wired = tracker !== "none";
124
134
 
125
- // Pass 1: github/linear pairs → chosen tracker's body; none → the pair's
126
- // trailing `false` block if present, else the generic skip message.
135
+ // Pass 1: tracker groups → chosen tracker's body; none → the group's trailing
136
+ // `false` block if present, else the generic skip message.
127
137
  let pairs = 0;
128
138
  let output = workflowContent.replace(
129
- PAIR_RE,
130
- (_match, gh: string, ln: string, falseBody: string | undefined) => {
139
+ GROUP_RE,
140
+ (match, gh: string, ln: string, jira: string | undefined, falseBody: string | undefined) => {
141
+ if (tracker === "jira" && jira === undefined) return match;
131
142
  pairs++;
132
143
  if (tracker === "github") return trimKeptContent(gh);
133
144
  if (tracker === "linear") return trimKeptContent(ln);
145
+ if (tracker === "jira") return trimKeptContent(jira!);
134
146
  return falseBody !== undefined ? trimKeptContent(falseBody) : NONE_STUB;
135
147
  },
136
148
  );
137
149
 
138
150
  // Pass 2: standalone conditional `true`/`false` blocks (any `false` attached to
139
- // a pair was already consumed in pass 1).
151
+ // a group was already consumed in pass 1).
140
152
  let conditionals = 0;
141
153
  for (const name of ["true", "false"] as const) {
142
154
  const active = name === "true" ? wired : !wired;
@@ -158,7 +170,7 @@ export function substituteWorkflow(
158
170
 
159
171
  /**
160
172
  * Find tracker markers that didn't participate in a successful resolution — a
161
- * lone github/linear block (not part of a complete pair) or an unbalanced
173
+ * block outside a complete group, a group lacking the chosen tracker, or an unbalanced
162
174
  * true/false pair.
163
175
  */
164
176
  function findOrphanMarkers(content: string): string[] {
@@ -154,6 +154,12 @@ export const BKIT_EGRESS_SOURCES: readonly EgressSource[] = [
154
154
  hosts: ["mcp.linear.app", "api.linear.app"],
155
155
  bases: ["linear.app"],
156
156
  },
157
+ {
158
+ id: "mcp-jira",
159
+ kind: "tracker-mcp",
160
+ hosts: ["mcp.atlassian.com"],
161
+ bases: ["atlassian.com"],
162
+ },
157
163
  {
158
164
  id: "agent-claude",
159
165
  kind: "agent-host",
@@ -15,6 +15,28 @@ import { isOpencodeProvider } from "../render/models.js";
15
15
  import type { OpencodeProvider } from "./egress.js";
16
16
  import { readPackageJson } from "./package-json.js";
17
17
 
18
+ /** The issue state a tracker sets when work starts (`progress`) and when it hands off to a human (`review`). */
19
+ export interface TrackerStates {
20
+ progress: string;
21
+ review: string;
22
+ }
23
+
24
+ /** `bkit.linear`: the team and project issues live in, and the state each moment moves to. */
25
+ export interface LinearConfig extends TrackerStates {
26
+ /** Team key, e.g. `ENG`. null = not configured. */
27
+ team: string | null;
28
+ /** Project name; new issues go into it and related-issue searches stay inside it. null = none. */
29
+ project: string | null;
30
+ }
31
+
32
+ /** `bkit.jira`: the site and project issues live in, and the status names each moment moves to. */
33
+ export interface JiraConfig extends TrackerStates {
34
+ /** Site URL, e.g. `https://acme.atlassian.net`; the MCP server's `cloudId`. null = not configured. */
35
+ site: string | null;
36
+ /** Project key, e.g. `MBA`. null = not configured. */
37
+ project: string | null;
38
+ }
39
+
18
40
  export interface BkitConfig {
19
41
  /** CI workflow file under `.github/workflows/`. */
20
42
  ciWorkflow: string;
@@ -26,12 +48,21 @@ export interface BkitConfig {
26
48
  worktreeInstall: boolean;
27
49
  /** Free GB under which worktree setup and `bkit disk prune --auto` run the max cleanup steps. */
28
50
  diskMinFreeGb: number;
29
- /** Which tracker issues live in: github, linear or none. */
51
+ /** Which tracker issues live in: github, linear, jira or none. */
30
52
  issueTracker: IssueTracker;
53
+ /** `bkit.linear`; each moment's state is a state name, or a state type such as `started`. */
54
+ linear: LinearConfig;
55
+ /** `bkit.jira`. */
56
+ jira: JiraConfig;
31
57
  /** The GitHub Projects v2 board settings; false = opted out, null = not configured. */
32
58
  githubProject: Record<string, unknown> | false | null;
33
59
  /** CI lanes whose `skipped` conclusion refuses a ship merge; empty = the capstone's green decides. */
34
60
  shipGateRequiredLanes: string[];
61
+ /**
62
+ * Globs (`:(glob)` git pathspecs) for paths a push may carry and still run only
63
+ * `bkit:gate:min` in `.husky/pre-push`; empty = every push runs the full hook.
64
+ */
65
+ minPushPaths: string[];
35
66
  /** The opencode provider recorded on install; null = absent or not a supported provider. */
36
67
  opencodeProvider: OpencodeProvider | null;
37
68
  /** Every installed opencode provider, supported ones only; empty = none recorded. */
@@ -53,8 +84,14 @@ export const CONFIG_DEFAULTS: Readonly<BkitConfig> = {
53
84
  worktreeInstall: true,
54
85
  diskMinFreeGb: 40,
55
86
  issueTracker: DEFAULT_ISSUE_TRACKER,
87
+ // `started` is a state type every Linear team has; In Review is a name a default team lacks.
88
+ linear: { team: null, project: null, progress: "started", review: "In Review" },
89
+ jira: { site: null, project: null, progress: "In Progress", review: "In Review" },
56
90
  githubProject: null,
57
91
  shipGateRequiredLanes: [],
92
+ // What bkit's workflows write: plan / design / build logs and the ledgers. Never
93
+ // `docs/**`: a project doc can be a test's input, so a docs edit can red a test.
94
+ minPushPaths: ["docs/plans/**", "docs/*.jsonl", ".bkit/*.jsonl"],
58
95
  opencodeProvider: null,
59
96
  opencodeProviders: [],
60
97
  cloudAgents: DEFAULT_CLOUD_AGENTS,
@@ -65,6 +102,19 @@ export const CONFIG_DEFAULTS: Readonly<BkitConfig> = {
65
102
 
66
103
  const nonEmptyString = (v: unknown): v is string => typeof v === "string" && v.trim() !== "";
67
104
 
105
+ const record = (v: unknown): Record<string, unknown> =>
106
+ v !== null && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
107
+
108
+ const optionalString = (v: unknown): string | null => (nonEmptyString(v) ? v.trim() : null);
109
+
110
+ /** Each moment's state from `raw`, else the default for that moment. */
111
+ function trackerStates(raw: Record<string, unknown>, defaults: TrackerStates): TrackerStates {
112
+ return {
113
+ progress: nonEmptyString(raw.progress) ? raw.progress.trim() : defaults.progress,
114
+ review: nonEmptyString(raw.review) ? raw.review.trim() : defaults.review,
115
+ };
116
+ }
117
+
68
118
  /**
69
119
  * Read `package.json` `bkit` from `root` (the main checkout). A missing file,
70
120
  * missing key, or wrongly typed value falls back to the default for that key.
@@ -78,8 +128,11 @@ export function readBkitConfig(root: string): BkitConfig {
78
128
  const minFreeGb = ((bkit.disk ?? {}) as Record<string, unknown>).minFreeGb;
79
129
  const project = bkit.githubProject;
80
130
  const lanes = bkit.shipGateRequiredLanes;
131
+ const book = bkit.minPushPaths;
81
132
  const provider = bkit.opencodeProvider;
82
133
  const providers = bkit.opencodeProviders;
134
+ const linear = record(bkit.linear);
135
+ const jira = record(bkit.jira);
83
136
  return {
84
137
  ciWorkflow: nonEmptyString(bkit.ciWorkflow) ? bkit.ciWorkflow : CONFIG_DEFAULTS.ciWorkflow,
85
138
  capstoneJob: nonEmptyString(bkit.capstoneJob) ? bkit.capstoneJob : CONFIG_DEFAULTS.capstoneJob,
@@ -94,6 +147,16 @@ export function readBkitConfig(root: string): BkitConfig {
94
147
  ? minFreeGb
95
148
  : CONFIG_DEFAULTS.diskMinFreeGb,
96
149
  issueTracker: parseIssueTracker(bkit.issueTracker) ?? CONFIG_DEFAULTS.issueTracker,
150
+ linear: {
151
+ team: optionalString(linear.team),
152
+ project: optionalString(linear.project),
153
+ ...trackerStates(linear, CONFIG_DEFAULTS.linear),
154
+ },
155
+ jira: {
156
+ site: nonEmptyString(jira.site) ? jira.site.trim().replace(/\/+$/, "") : null,
157
+ project: optionalString(jira.project),
158
+ ...trackerStates(jira, CONFIG_DEFAULTS.jira),
159
+ },
97
160
  githubProject:
98
161
  project === false
99
162
  ? false
@@ -101,6 +164,10 @@ export function readBkitConfig(root: string): BkitConfig {
101
164
  ? (project as Record<string, unknown>)
102
165
  : null,
103
166
  shipGateRequiredLanes: Array.isArray(lanes) ? lanes.filter(nonEmptyString) : [],
167
+ // An explicit [] is kept: it switches the min push off.
168
+ minPushPaths: Array.isArray(book)
169
+ ? book.filter(nonEmptyString)
170
+ : [...CONFIG_DEFAULTS.minPushPaths],
104
171
  opencodeProvider:
105
172
  typeof provider === "string" && isOpencodeProvider(provider) ? provider : null,
106
173
  opencodeProviders: Array.isArray(providers)
@@ -114,3 +181,23 @@ export function readBkitConfig(root: string): BkitConfig {
114
181
  cloudAgentsExplicit: bkit.cloudAgents !== undefined,
115
182
  };
116
183
  }
184
+
185
+ /** Where the wired tracker's issues live, for the workflows' tracker calls. */
186
+ export interface TrackerScope {
187
+ /** Linear team key; null under any other tracker or when unset. */
188
+ trackerTeam: string | null;
189
+ /** Linear project name or Jira project key; null under github / none or when unset. */
190
+ trackerProject: string | null;
191
+ /** Jira site URL (the MCP `cloudId`); null under any other tracker or when unset. */
192
+ trackerSite: string | null;
193
+ }
194
+
195
+ export function trackerScope(
196
+ cfg: Pick<BkitConfig, "issueTracker" | "linear" | "jira">,
197
+ ): TrackerScope {
198
+ if (cfg.issueTracker === "linear")
199
+ return { trackerTeam: cfg.linear.team, trackerProject: cfg.linear.project, trackerSite: null };
200
+ if (cfg.issueTracker === "jira")
201
+ return { trackerTeam: null, trackerProject: cfg.jira.project, trackerSite: cfg.jira.site };
202
+ return { trackerTeam: null, trackerProject: null, trackerSite: null };
203
+ }
@@ -124,7 +124,7 @@ function gitAskRule(g) {
124
124
  : null;
125
125
  }
126
126
  case "stash":
127
- return g.args[0] === "drop" ? "git stash drop" : null;
127
+ return g.args[0] === "drop" || g.args[0] === "clear" ? `git stash ${g.args[0]}` : null;
128
128
  case "rebase":
129
129
  return g.short.has("i") || g.long.has("--interactive") ? "git rebase -i" : null;
130
130
  case "filter-branch":
@@ -15,11 +15,18 @@ tools:
15
15
  # <!-- bkit:tracker github start -->
16
16
  - WebSearch
17
17
  - mcp__github__add_issue_comment
18
+ - mcp__github__search_issues
18
19
  # <!-- bkit:tracker github end -->
19
20
  # <!-- bkit:tracker linear start -->
20
21
  - WebSearch
21
22
  - mcp__linear__save_comment
23
+ - mcp__linear__list_issues
22
24
  # <!-- bkit:tracker linear end -->
25
+ # <!-- bkit:tracker jira start -->
26
+ - WebSearch
27
+ - mcp__jira__addOrEditJiraIssueComment
28
+ - mcp__jira__searchJiraIssuesUsingJql
29
+ # <!-- bkit:tracker jira end -->
23
30
  # <!-- bkit:tracker false start -->
24
31
  - WebSearch
25
32
  # <!-- bkit:tracker false end -->
@@ -46,10 +53,10 @@ maxTurns: 400
46
53
 
47
54
  - **Read / Update / Create:** Use any appended Read / Update / Create as exact I/O paths.
48
55
  - **Mandate:** Generate audit report and ledger entries; do not just analyse; do not plan, build, install, fix findings, or create tracker issues.
49
- - **Tracker:** Comment-only; never create, close, or relabel issues; post one summary comment on the issue named in input.
56
+ - **Tracker:** Comment-only; NEVER create, close, or relabel issues; recommend and let caller act.
50
57
  - **Completeness:** report carries every template section; no `PENDING` left.
51
58
  - **Output header:** All lines above `<!-- verdict:end -->` MUST be machine-parseable.
52
- - **Destructive git PROHIBITED:** NEVER run any of these: `git reset` (any flavour), `git checkout -- .`, `git restore .`, `git clean` (any flavour), `git rebase -i`, `git stash drop`, `git push --force` (any flavour).
59
+ - **Destructive git PROHIBITED:** NEVER run any of these: `git reset` (any flavour), `git checkout -- .`, `git restore .`, `git clean` (any flavour), `git rebase -i`, `git stash drop`, `git stash clear`, `git push --force` (any flavour).
53
60
 
54
61
  **Process:**
55
62
 
@@ -94,38 +101,60 @@ maxTurns: 400
94
101
  ```
95
102
  Plain text, not JSON. Hold stdout as `{BKIT_TIPS}`; prints nothing or exits non-zero → `{BKIT_TIPS}` empty.
96
103
  15. <!-- bkit:tracker true start -->
97
- Post summary to issue; runs after any STOP too. Scan input only, never files read:
104
+ Post summary to issue or find audit parent; runs after any STOP too. Scan input only, never files read:
98
105
  <!-- bkit:tracker github start -->
99
106
  `<id>{N}</id>`, `<github_issue>{N}</github_issue>`, `GitHub issue: #{N}`, `ISSUE-{N}`, or bare `#{N}` → numeric N → `ISSUE_ID`.
100
107
  <!-- bkit:tracker github end -->
101
108
  <!-- bkit:tracker linear start -->
102
109
  `<id>{ID}</id>`, `<linear_issue>{ID}</linear_issue>`, `Linear issue: {ID}`, `ISSUE-{ID}`, or scan for `[A-Z]+-\d+` pattern → first match → `ISSUE_ID`.
103
110
  <!-- bkit:tracker linear end -->
104
- **If** no `ISSUE_ID` → `Issue` = `None`; skip step; never create a tracker issue. **Else**:
105
- 1. Read repo facts; **If** non-zero → `Issue` = `{ISSUE_ID} failed`; skip step:
111
+ <!-- bkit:tracker jira start -->
112
+ `<id>{ID}</id>`, `<jira_issue>{ID}</jira_issue>`, `Jira issue: {ID}`, `ISSUE-{ID}`, a `/browse/{ID}` link, or `[A-Z][A-Z0-9]+-\d+` → first match → `ISSUE_ID`.
113
+ <!-- bkit:tracker jira end -->
114
+ 1. Read repo facts; **If** non-zero → `Issue` = `{ISSUE_ID} failed` (no `ISSUE_ID` → `None`), `Parent` = `unchecked`; skip step:
106
115
  ```bash
107
116
  "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" repo info --allow-detached
108
117
  ```
109
- Hold `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as `{BRANCH}`, `outboxRoot` as `{OUTBOX_ROOT}`.
110
- 2. Write Output format content from `## Stopped` through `## Recommended Next Step` to `{OUTBOX_ROOT}/audit-{slug}/comment.md`; `Embedded Directives` names sources only, never directive text.
111
- 3. Build body; **If** non-zero → `Issue` = `{ISSUE_ID} failed`; skip step:
118
+ Hold `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as `{BRANCH}`, `outboxRoot` as `{OUTBOX_ROOT}`, `trackerProject` as `{TRACKER_PROJECT}`, `trackerSite` as `{TRACKER_SITE}`.
119
+ 2. **If** `ISSUE_ID` → `Parent` = `{ISSUE_ID} named`, `{PARENT_REF}` = `{ISSUE_ID}`. **Else** → find the template's audit parent = one open standing issue every run of this template reports to; never create tracker issues. `{TPL}` = `docs/templates/bkit-audit-{slug}.md`; take first hit in rank order that is open and whose body contains `{TPL}`:
120
+ <!-- bkit:tracker github start -->
121
+ `mcp__github__search_issues({ owner: "{OWNER}", repo: "{REPO}", query: "standing audit parent issue that runs {TPL}", perPage: 10, fields: ["number", "title", "state", "body", "html_url"] })` → `ISSUE_ID` = `{number}`, `Parent` = `#{number} found`, `{PARENT_REF}` = `#{number} — {title}` + `html_url`.
122
+ <!-- bkit:tracker github end -->
123
+ <!-- bkit:tracker linear start -->
124
+ `mcp__linear__list_issues({ query: "{TPL}", limit: 10 })` (open = not completed / canceled; body = `description`) → `ISSUE_ID` = `{identifier}`, `Parent` = `{identifier} found`, `{PARENT_REF}` = `{identifier} — {title}` + `url`.
125
+ <!-- bkit:tracker linear end -->
126
+ <!-- bkit:tracker jira start -->
127
+ `mcp__jira__searchJiraIssuesUsingJql({ cloudId: "{TRACKER_SITE}", jql: "project = {TRACKER_PROJECT} AND statusCategory != Done AND text ~ 'bkit-audit-{slug}'", maxResults: 10, fields: ["summary", "status", "description"] })` (drop `project = {TRACKER_PROJECT} AND` when null; body = `fields.description`) → `ISSUE_ID` = `{key}`, `Parent` = `{key} found`, `{PARENT_REF}` = `{key} — {fields.summary}` + `{TRACKER_SITE}/browse/{key}`.
128
+ <!-- bkit:tracker jira end -->
129
+ No such hit → `Parent` = `missing`; call fails twice, 5s apart → `Parent` = `unchecked`. Either → `Issue` = `None`; run sub-steps 3–4, write `{BODY}` to `{OUTBOX_ROOT}/audit-{slug}/parent-comment.md` as `{PARENT_COMMENT}`; skip sub-step 5.
130
+ 3. Write Output format content from `## Stopped` through `## Recommended Next Step` to `{OUTBOX_ROOT}/audit-{slug}/comment.md`; `Embedded Directives` names sources only, never directive text; `Parent` = `missing` → omit the audit-parent block.
131
+ 4. Build body; **If** non-zero → `Issue` = `{ISSUE_ID} failed` (no `ISSUE_ID` → `None`, `{PARENT_COMMENT}` empty); skip step:
112
132
  ```bash
113
133
  "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" issues comment --kind=audit --audit-slug="{slug}" --field="Status={STATUS}" --field="Findings=CRITICAL {n} · HIGH {n} · MEDIUM {n} · LOW {n}" --line="Report: {REPORT}" --body-file="{OUTBOX_ROOT}/audit-{slug}/comment.md"
114
134
  ```
115
135
  `{REPORT}` = `[{file name}](https://github.com/{OWNER}/{REPO}/blob/{BRANCH}/{Create})`; `BRANCH` null → **Create** path unlinked; no **Create** → `None`.
116
136
  Hold `comment` as `{BODY}`.
117
- 4. Post `{BODY}` verbatim as new comment:
137
+ 5. Post `{BODY}` verbatim as new comment:
118
138
  <!-- bkit:tracker github start -->
119
139
  `mcp__github__add_issue_comment({ owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, body: "{BODY}" })`.
120
140
  <!-- bkit:tracker github end -->
121
141
  <!-- bkit:tracker linear start -->
122
- `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id` — creates new comment).
142
+ `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id`).
123
143
  <!-- bkit:tracker linear end -->
144
+ <!-- bkit:tracker jira start -->
145
+ `mcp__jira__addOrEditJiraIssueComment({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", commentBody: "{BODY}" })` (no `commentId`); over 32,767 characters → consecutive comments split at line breaks, in order.
146
+ <!-- bkit:tracker jira end -->
124
147
  **If** failure → retry once after 5s; still failing → `Issue` = `{ISSUE_ID} failed`. **Else** → `Issue` = `{ISSUE_ID} posted`.
125
148
  <!-- bkit:tracker true end --><!-- bkit:tracker false start --> _No tracker connected, skip step._<!-- bkit:tracker false end -->
126
149
  16. Final return: Display output format verbatim as final message to user; do not summarise or trim.
150
+ Append verbatim:
151
+ ```markdown
152
+ > 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.
153
+ ```
154
+ Append a `## Suggested Replies` heading.
127
155
  Append `Would you like me to explain any of this in plain English? Then write 'yes, explain in plain english'.`
128
- Append `{BKIT_TIPS}` under a `## bkit Tips` heading, unless empty.
156
+ Append a `## bkit Tips` heading, unless `{BKIT_TIPS}` is empty.
157
+ Append `{BKIT_TIPS}`, unless empty.
129
158
 
130
159
  **Report format:**
131
160
 
@@ -138,6 +167,7 @@ Status: COMPLETE | STOPPED
138
167
  Report: [**Create** path. **If** none → `None`.]
139
168
  Findings: CRITICAL {n} · HIGH {n} · MEDIUM {n} · LOW {n}
140
169
  Issue: [Issue ID, then `posted` or `failed`. **If** none → `None`.]
170
+ Parent: [Audit parent ID, then `named` or `found`; or `missing` or `unchecked`. **If** no tracker → `None`.]
141
171
 
142
172
  <!-- verdict:end -->
143
173
 
@@ -173,7 +203,7 @@ Issue: [Issue ID, then `posted` or `failed`. **If** none → `None`.]
173
203
 
174
204
  ## Recommended Next Step
175
205
 
176
- [Copy-paste handoff. Advisory only, never auto-trigger. Emit `text` block: L1 `Create issues: Suggested Issues rows {rows to file}, bodies per .bkit/trackers.md § Issue shapes, each with **Audit reports:** {report path} (findings {row's IDs})`; L2 `{command} {new issue for that row}`; L3 `Brief: {row title, report link — 1-2 lines}`. **If** none → `None`.]
206
+ [Copy-paste handoff. Advisory only, never auto-trigger. **If** `Parent` = `missing` → first emit `text` block: L1 `Create audit parent (one per template, every run reports to it; stays open): title {template H1 title}; labels, project, milestone per .agents/rules.md § Tracker issue settings, no workflow or next:* label; body:`; L2 `Standing parent for docs/templates/bkit-audit-{slug}.md. Each run posts its summary here; issues filed from a run's Suggested Issues are its sub-issues. Reports: docs/audits/{YYYYMM}/{slug}.md.`; L3 `Run: @bkit-audit-generate docs/templates/bkit-audit-{slug}.md {this issue's ID}`; L4 `After filing: post {PARENT_COMMENT} verbatim as its first comment`. **If** `Parent` = `unchecked` → first emit `text` block: L1 `Post {PARENT_COMMENT} verbatim on this template's open audit parent; none → create one per .bkit/trackers.md § Issue shapes, then post`. `{PARENT_COMMENT}` empty → drop the post line. Then emit `text` block: L1 `Create issues: Suggested Issues rows {rows to file}, as sub-issues of {parent}, bodies per .bkit/trackers.md § Issue shapes, each with **Audit reports:** {report path} (findings {row's IDs})`; `{parent}` = `{PARENT_REF}`; `missing` → `the audit parent above`; `unchecked` → `that audit parent`; no tracker → drop `, as sub-issues of {parent}`; L2 `{command} {new issue for that row}`; L3 `Brief: {row title, report link — 1-2 lines}`. **If** no rows to file → that block `None`.]
177
207
  ```
178
208
 
179
209
  > ⛔ **STOP after generating audit report and producing output. Do not code or apply fixes.**
@@ -35,7 +35,7 @@ maxTurns: 200
35
35
  - **Mandate:** Apply challenge fixes (edit / create source files); only identified findings, no new scope; do not just analyse.
36
36
  - **Blockers:** Append `BLOCKED` log line per blocked finding; no out-of-scope deferral.
37
37
  - **Output header:** All lines above `<!-- verdict:end -->` MUST be machine-parseable.
38
- - **Destructive git PROHIBITED:** NEVER run any of these: `git reset` (any flavour), `git checkout -- .`, `git restore .`, `git clean` (any flavour), `git rebase -i`, `git stash drop`, `git push --force` (any flavour).
38
+ - **Destructive git PROHIBITED:** NEVER run any of these: `git reset` (any flavour), `git checkout -- .`, `git restore .`, `git clean` (any flavour), `git rebase -i`, `git stash drop`, `git stash clear`, `git push --force` (any flavour).
39
39
 
40
40
  **Process:**
41
41