@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
@@ -28,18 +28,25 @@ description: "Ship Feature — Autonomous merge and archive"
28
28
 
29
29
  <!-- bkit:tracker github start -->
30
30
 
31
- > - **Tracker:** GitHub Issues via MCP server `github` (configured in `.mcp.json` `mcpServers.github`). Tool names: `mcp__github__issue_read` (methods `get`, `get_comments`, `get_labels`), `mcp__github__issue_write` (method: `update`), `mcp__github__add_issue_comment`, `mcp__github__list_issues`, `mcp__github__projects_write` (methods `add_project_item` / `update_project_item`), `mcp__github__projects_list` (method `list_project_items`) — needs `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) and `package.json` `bkit.githubProject` config; absent either → board status sync silently skipped. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; all writes best-effort; never gate. **If** failure → retry once after 5s, then continue.
32
- > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive — drop old phase before adding new; a phase start also drops every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
33
- > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__github__add_issue_comment({ owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, body: "{BODY}" })` before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. Comment ID tracking not required.
31
+ > - **Tracker:** GitHub Issues via MCP server `github` (`.mcp.json` `mcpServers.github`). Tools: `mcp__github__issue_read` (method `get` / `get_comments` / `get_labels`), `mcp__github__issue_write` (method `update`), `mcp__github__add_issue_comment`, `mcp__github__list_issues`, `mcp__github__projects_write` (method `add_project_item` / `update_project_item`), `mcp__github__projects_list` (method `list_project_items`); board status sync needs `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) and `package.json` `bkit.githubProject`, absent either → silently skipped. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; writes best-effort, never gate; **If** failure → retry once after 5s → continue.
32
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
33
+ > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__github__add_issue_comment({ owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, body: "{BODY}" })` before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content.
34
34
 
35
35
  <!-- bkit:tracker github end -->
36
36
  <!-- bkit:tracker linear start -->
37
37
 
38
- > - **Tracker:** Linear via MCP server `linear` (configured in `.mcp.json` `mcpServers.linear`). Tool names: `mcp__linear__get_issue`, `mcp__linear__save_issue`, `mcp__linear__save_comment`, `mcp__linear__list_comments`, `mcp__linear__list_issues`. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; all `save_*` writes best-effort; never gate. **If** failure → retry once after 5s, then continue. `save_issue` always includes `id`.
39
- > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive — drop old phase before adding new; a phase start also drops every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
40
- > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id` — creates new comment) before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. No edit-in-place.
38
+ > - **Tracker:** Linear via MCP server `linear` (`.mcp.json` `mcpServers.linear`). Tools: `mcp__linear__get_issue`, `mcp__linear__save_issue`, `mcp__linear__save_issue_label`, `mcp__linear__save_comment`, `mcp__linear__list_comments`, `mcp__linear__list_issues`. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; `save_*` writes best-effort, never gate; **If** failure → retry once after 5s → continue. `save_issue` always includes `id` and is all-or-nothing (one state or label name the team lacks rejects the whole call) → labels and state in separate calls, labels first; create each printed `add` entry first via `save_issue_label({ name })` (`already exists` = done). `Could not find state` / `Could not find label` → log `Unapplied: <state|label> "<name>" not in team`, no retry, continue.
39
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
40
+ > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id`) before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content.
41
41
 
42
42
  <!-- bkit:tracker linear end -->
43
+ <!-- bkit:tracker jira start -->
44
+
45
+ > - **Tracker:** Jira via MCP server `jira` (`.mcp.json` `mcpServers.jira`). Tools: `mcp__jira__getJiraIssue`, `mcp__jira__editJiraIssue`, `mcp__jira__transitionJiraIssue`, `mcp__jira__addOrEditJiraIssueComment`, `mcp__jira__searchJiraIssuesUsingJql`, `mcp__jira__executeRead`; every call passes `cloudId: "{TRACKER_SITE}"`. Assert `{ISSUE_ID}` / `{TRACKER_SITE}` / `{STATE}` / `{LABELS}` non-empty before tool calls; writes best-effort, never gate; **If** failure → retry once after 5s → continue. `getJiraIssue` always passes `view: "evidence"` (other views omit labels). `editJiraIssue` `fields.labels` replaces the whole set → pass full printed `LABELS`; labels and status in separate calls, labels first; never pass `fields` / `update` to `transitionJiraIssue`. Status change: `executeRead({ name: "listJiraIssueTransitions", inputs: { issueIdOrKey } })` → transition whose `to.name` = target status → `transitionJiraIssue({ issueIdOrKey, transitionId })`; none → log `Unapplied: status "<name>" not reachable`, no retry, continue. Comment reads: `executeRead({ name: "listJiraIssueComments", inputs: { issueIdOrKey, maxResults: 100, startAt } })`, oldest first, raise `startAt` while `isLast` is false; page with `appliedContentFormat` = `html` → re-read it one comment per call (`maxResults: 1`).
46
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
47
+ > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__jira__addOrEditJiraIssueComment({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", commentBody: "{BODY}" })` (no `commentId`) before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. Body over 32,767 characters → post as consecutive comments split at line breaks, in order.
48
+
49
+ <!-- bkit:tracker jira end -->
43
50
 
44
51
  > - **Timeouts:** **If** workflow or subagent run > 3600 seconds → **Failure Path**.
45
52
  > - **Limits:** `MAX_MERGE_ATTEMPT` and `MAX_REVALIDATE_ATTEMPT` resolved by name via `bkit counters route --limit=` in fenced routing blocks below.
@@ -56,13 +63,16 @@ description: "Ship Feature — Autonomous merge and archive"
56
63
  ```bash
57
64
  "{BKIT}" workflows fail --workflow=ship --fid={FID} --month={YYYYMM} --token={LOCK_TOKEN} --max-exceeded --pr={PR_NUMBER} {LABEL_FLAGS} --step-number={N} --step-title="{Step Name}" --sub-step={M} --error-file="{OUTBOX_ROOT}/error.md" --stderr-file="{STDERR_FILE}"
58
65
  ```
59
- → hold `handoverNeeded` as `{HANDOVER_NEEDED}`, `labels` as `{LABELS}`. **If** exit non-zero → log `Lock removal failed` with the printed `lock` to stderr, continue.
66
+ → hold `handoverNeeded` as `{HANDOVER_NEEDED}`, `labels` as `{LABELS}`, `trackerState` as `{TRACKER_STATE}`. **If** exit non-zero → log `Lock removal failed` with the printed `lock` to stderr, continue.
60
67
  2. <!-- bkit:tracker github start -->
61
68
  `mcp__github__issue_write({ method: "update", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, labels: [{LABELS}] })`.
62
69
  <!-- bkit:tracker github end -->
63
70
  <!-- bkit:tracker linear start -->
64
- `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "In Review", labels: [{LABELS}] })`.
71
+ `mcp__linear__save_issue_label({ name })` per printed `add` entry → `mcp__linear__save_issue({ id: "{ISSUE_ID}", labels: [{LABELS}] })` → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{TRACKER_STATE}" })`.
65
72
  <!-- bkit:tracker linear end -->
73
+ <!-- bkit:tracker jira start -->
74
+ `mcp__jira__editJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", fields: { labels: [{LABELS}] } })` → move status to `{TRACKER_STATE}` (**Tracker** status change).
75
+ <!-- bkit:tracker jira end -->
66
76
  <!-- bkit:tracker true start -->
67
77
  Post `comment` (when non-null).
68
78
  <!-- bkit:tracker true end -->
@@ -87,15 +97,21 @@ description: "Ship Feature — Autonomous merge and archive"
87
97
  "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" repo info --fetch
88
98
  ```
89
99
  → hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as initial `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`, `bkitAdvisory` as `{BKIT_ADVISORY}`. **If** `BKIT_ADVISORY` != null → emit advisory `[bkit-ship] {BKIT_ADVISORY}`.
100
+ <!-- bkit:tracker true start -->
101
+ Hold `trackerTeam` as `{TRACKER_TEAM}`, `trackerProject` as `{TRACKER_PROJECT}`, `trackerSite` as `{TRACKER_SITE}`.
102
+ <!-- bkit:tracker true end -->
90
103
  2. **If** `ISSUE_ID` already set by AGENTS.md → skip. **Else**:
91
104
  <!-- bkit:tracker github start -->
92
105
  Extract from session prompt: `<id>{N}</id>`, `<github_issue>{N}</github_issue>`, `GitHub issue: #{N}`, `ISSUE-{N}`, or bare `#{N}` → numeric N → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
93
106
  <!-- bkit:tracker github end -->
94
107
  <!-- bkit:tracker linear start -->
95
- Extract from session prompt: `<id>{ID}</id>`, `<linear_issue>{ID}</linear_issue>`, `Linear issue: {ID}`, `ISSUE-{ID}`, or scan for `[A-Z]+-\d+` pattern → first match → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
108
+ Extract from session prompt: `<id>{ID}</id>`, `<linear_issue>{ID}</linear_issue>`, `Linear issue: {ID}`, `ISSUE-{ID}`, or `[A-Z]+-\d+` → first match → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
96
109
  <!-- bkit:tracker linear end -->
110
+ <!-- bkit:tracker jira start -->
111
+ Extract from session prompt: `<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`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
112
+ <!-- bkit:tracker jira end -->
97
113
  <!-- bkit:tracker false start -->
98
- Scan session prompt for `<id>{ID}</id>` or `ISSUE-{ID}` → first match → `ISSUE_ID`. **If** no `ID` found → set `ISSUE_ID=""` and log `Tracker not wired — proceeding without issue ID.` Workflow continues with FID derived from branch name.
114
+ Scan session prompt for `<id>{ID}</id>` or `ISSUE-{ID}` → first match → `ISSUE_ID`. **If** no `ID` found → set `ISSUE_ID=""`, log `Tracker not wired — proceeding without issue ID.`, continue with FID derived from branch name.
99
115
  <!-- bkit:tracker false end -->
100
116
  3. **If** `LABELS`, `DESCRIPTION`, `COMMENTS` already set by AGENTS.md → sort `COMMENTS` oldest to newest → skip. **Else**:
101
117
  <!-- bkit:tracker github start -->
@@ -104,8 +120,11 @@ description: "Ship Feature — Autonomous merge and archive"
104
120
  <!-- bkit:tracker linear start -->
105
121
  `mcp__linear__get_issue({ id: "{ISSUE_ID}" })` → extract `state.name` → `STATE`; `labels[].name` → `LABELS`; `description` → `DESCRIPTION`; `title` → `TITLE`; `url` → `URL`. Then `mcp__linear__list_comments({ issueId: "{ISSUE_ID}", orderBy: "createdAt desc", limit: 250 })` → sort oldest to newest → `COMMENTS`.
106
122
  <!-- bkit:tracker linear end -->
123
+ <!-- bkit:tracker jira start -->
124
+ `mcp__jira__getJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", view: "evidence" })` → extract `fields.status.name` → `STATE`; `fields.labels` → `LABELS`; `fields.description` → `DESCRIPTION`; `fields.summary` → `TITLE`; `{TRACKER_SITE}/browse/{ISSUE_ID}` → `URL`. Then read comments (**Tracker** comment reads) → `COMMENTS`.
125
+ <!-- bkit:tracker jira end -->
107
126
  <!-- bkit:tracker false start -->
108
- No tracker wired — set `STATE`, `LABELS`, `DESCRIPTION`, `COMMENTS` all empty; the input artifact is built from the session prompt alone.
127
+ No tracker wired → `STATE`, `LABELS`, `DESCRIPTION`, `COMMENTS` all empty; input artifact built from session prompt alone.
109
128
  <!-- bkit:tracker false end -->
110
129
  4. Resolve `FID` — first match wins; never borrow another feature's `FID` from a leftover lock or the newest bucket:
111
130
  1. Session prompt names it — an `FID` slug, a `feat/{FID}` branch, or a path under `docs/plans/{YYYYMM}/` (`{FID}-design.md`, `{FID}-plan.md`, `logs/{FID}/`).
@@ -163,15 +182,18 @@ description: "Ship Feature — Autonomous merge and archive"
163
182
  ```bash
164
183
  "{BKIT}" issues labels --phase=ship --board=progress --issue="{ISSUE_ID}" --owner-repo="{OWNER_REPO}" {LABEL_FLAGS}
165
184
  ```
166
- → hold `labels` as `{LABELS}`, `board` as `{BOARD}`, `boardSkipped`.
185
+ → hold `labels` as `{LABELS}`, `trackerState` as `{TRACKER_STATE}`, `board` as `{BOARD}`, `boardSkipped`.
167
186
  <!-- bkit:tracker true end -->
168
187
  <!-- bkit:tracker github start -->
169
188
  `mcp__github__issue_write({ method: "update", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, labels: [{LABELS}] })`.
170
- **If** `BOARD` = null → log `boardSkipped` → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → resolve numeric item id `mcp__github__projects_list({BOARD}.listItems)` → entry whose content issue number == `{ISSUE_ID}` → numeric `id` → `{ITEM_ID}` → set status `mcp__github__projects_write({BOARD}.updateItem + item_id: {ITEM_ID})`.
189
+ **If** `BOARD` = null → log `boardSkipped` → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → `mcp__github__projects_list({BOARD}.listItems)` → numeric `id` of entry whose content issue number == `{ISSUE_ID}` → `{ITEM_ID}` → set status `mcp__github__projects_write({BOARD}.updateItem + item_id: {ITEM_ID})`.
171
190
  <!-- bkit:tracker github end -->
172
191
  <!-- bkit:tracker linear start -->
173
- `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "In Progress", labels: [{LABELS}] })`.
192
+ `mcp__linear__save_issue_label({ name })` per printed `add` entry → `mcp__linear__save_issue({ id: "{ISSUE_ID}", labels: [{LABELS}] })` → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{TRACKER_STATE}" })`.
174
193
  <!-- bkit:tracker linear end -->
194
+ <!-- bkit:tracker jira start -->
195
+ `mcp__jira__editJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", fields: { labels: [{LABELS}] } })` → move status to `{TRACKER_STATE}` (**Tracker** status change).
196
+ <!-- bkit:tracker jira end -->
175
197
  10. Create the outbox (`{OUTBOX}` = `{OUTBOX_ROOT}/{FID}`) and run the repo preflight:
176
198
  ```bash
177
199
  mkdir -p "{OUTBOX}" || exit 1
@@ -489,6 +511,9 @@ description: "Ship Feature — Autonomous merge and archive"
489
511
  <!-- bkit:tracker linear start -->
490
512
  `mcp__linear__get_issue({ id: "{ISSUE_ID}" })` → extract `labels[].name` → `LABELS`.
491
513
  <!-- bkit:tracker linear end -->
514
+ <!-- bkit:tracker jira start -->
515
+ `mcp__jira__getJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", view: "evidence" })` → extract `fields.labels` → `LABELS`.
516
+ <!-- bkit:tracker jira end -->
492
517
  ```bash
493
518
  "{BKIT}" prs merge --number="{PR_NUMBER}" --match-head="{GATE_HEAD}" --delete-branch {LABEL_FLAGS} --expect-merged
494
519
  ```
@@ -602,15 +627,18 @@ description: "Ship Feature — Autonomous merge and archive"
602
627
  ```bash
603
628
  "{BKIT}" issues labels --phase=merged --board=review --issue="{ISSUE_ID}" --owner-repo="{OWNER_REPO}" {LABEL_FLAGS}
604
629
  ```
605
- → hold `labels` as `{LABELS}`, `board` as `{BOARD}`, `boardSkipped`.
630
+ → hold `labels` as `{LABELS}`, `trackerState` as `{TRACKER_STATE}`, `board` as `{BOARD}`, `boardSkipped`.
606
631
  <!-- bkit:tracker true end -->
607
632
  <!-- bkit:tracker github start -->
608
633
  `mcp__github__issue_write({ method: "update", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, labels: [{LABELS}] })`. Do not close the issue.
609
- **If** `BOARD` = null → log `boardSkipped` → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → resolve numeric item id `mcp__github__projects_list({BOARD}.listItems)` → entry whose content issue number == `{ISSUE_ID}` → numeric `id` → `{ITEM_ID}` → set status `mcp__github__projects_write({BOARD}.updateItem + item_id: {ITEM_ID})`.
634
+ **If** `BOARD` = null → log `boardSkipped` → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → `mcp__github__projects_list({BOARD}.listItems)` → numeric `id` of entry whose content issue number == `{ISSUE_ID}` → `{ITEM_ID}` → set status `mcp__github__projects_write({BOARD}.updateItem + item_id: {ITEM_ID})`.
610
635
  <!-- bkit:tracker github end -->
611
636
  <!-- bkit:tracker linear start -->
612
- `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "In Review", labels: [{LABELS}] })`. Do not set Done.
637
+ `mcp__linear__save_issue_label({ name })` per printed `add` entry → `mcp__linear__save_issue({ id: "{ISSUE_ID}", labels: [{LABELS}] })` → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{TRACKER_STATE}" })`. Do not set Done.
613
638
  <!-- bkit:tracker linear end -->
639
+ <!-- bkit:tracker jira start -->
640
+ `mcp__jira__editJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", fields: { labels: [{LABELS}] } })` → move status to `{TRACKER_STATE}` (**Tracker** status change). Do not set Done.
641
+ <!-- bkit:tracker jira end -->
614
642
  4. Collect setup tips:
615
643
  ```bash
616
644
  "{BKIT}" tips --workflow=ship
@@ -620,8 +648,10 @@ description: "Ship Feature — Autonomous merge and archive"
620
648
  <!-- bkit:tracker true start -->
621
649
  Append issue link [{ISSUE_ID} {TITLE}]({URL})
622
650
  <!-- bkit:tracker true end -->
651
+ Append a `## Suggested Replies` heading.
623
652
  Append `Would you like me to explain any of this in plain English? Then write 'yes, explain in plain english'.`
624
- Append `{BKIT_TIPS}` under a `## bkit Tips` heading, unless empty.
653
+ Append a `## bkit Tips` heading, unless `{BKIT_TIPS}` is empty.
654
+ Append `{BKIT_TIPS}`, unless empty.
625
655
  6. **If** user requests plain English explanation → restate the summary in plain English; name terms and say what they mean; identifiers stay verbatim; plainness lives in sentences, NOT nouns; do not re-run any step.
626
656
 
627
657
  ### 🔒 Gate 14 — Close Workflow
@@ -71,6 +71,14 @@ BKIT_GH_TOKEN=
71
71
  # Generate at: https://linear.app/settings/api
72
72
  BKIT_LINEAR_API_KEY=
73
73
 
74
+ # BKIT_JIRA_API_TOKEN — Atlassian API token for the Jira MCP server
75
+ # (mcp.atlassian.com/v2/mcp), sent as `Authorization: Bearer`. Create it with
76
+ # "Create API token with scopes" and pick the app "Atlassian MCP V2"; a classic
77
+ # token or another app is refused. An org admin must first allow API-token sign-in
78
+ # for the Rovo MCP server. Steps: .bkit/trackers.md § jira.
79
+ # Generate at: https://id.atlassian.com/manage-profile/security/api-tokens
80
+ BKIT_JIRA_API_TOKEN=
81
+
74
82
  # BKIT_ANTHROPIC_API_KEY — Anthropic API key. Only needed if you run Claude Code
75
83
  # without a Claude subscription (pay-per-token mode). Subscription users leave
76
84
  # blank.
@@ -5,8 +5,8 @@
5
5
  "Skill(*)",
6
6
  "Bash(*)",
7
7
  "mcp__github__*",
8
- "mcp__claude_ai_Linear__*",
9
8
  "mcp__linear__*",
9
+ "mcp__jira__*",
10
10
  "WebSearch",
11
11
  "Bash(git push --force-with-lease:*)",
12
12
  "Read(./.env.example)",
@@ -61,11 +61,13 @@
61
61
  "Bash(git checkout -- .:*)",
62
62
  "Bash(git restore .:*)",
63
63
  "Bash(git stash drop:*)",
64
+ "Bash(git stash clear:*)",
64
65
  "Bash(git rebase -i:*)",
65
66
  "Bash(gh repo delete:*)",
66
67
  "Bash(gh pr close:*)",
67
68
  "Bash(gh release delete:*)",
68
69
  "Bash(git reset *--hard*)",
70
+ "Bash(git -* reset *--hard*)",
69
71
  "Bash(git clean -*f*)",
70
72
  "Bash(git checkout *.)",
71
73
  "Bash(git checkout * . *)",
@@ -41,7 +41,7 @@ Add **each** line below as a secret (Name = the key, Value = the value). Set the
41
41
 
42
42
  @@CLOUD_ENV_NOTES@@
43
43
 
44
- - `LINEAR_ISSUE_ID` (Linear tracker) / `GITHUB_ISSUE_ID` (GitHub tracker) are injected
44
+ - `GITHUB_ISSUE_ID` (GitHub tracker) / `LINEAR_ISSUE_ID` (Linear tracker) are injected
45
45
  **per session** by the Cursor integration — do **not** add them here.
46
46
  - `BKIT_GH_TOKEN` PAT permissions (fine-grained for one owner, classic across owners) are documented in `.bkit/cloud.md`
47
47
  § `BKIT_GH_TOKEN` — token permissions (identical scope to the Claude side).
@@ -79,6 +79,6 @@ Your `/bkit-*` commands and bkit subagents load automatically from the committed
79
79
 
80
80
  ---
81
81
 
82
- Tracker dispatch (Linear `@cursor` mention / GitHub PR-label automation), the
82
+ Tracker dispatch (GitHub PR-label automation / Linear `@cursor` mention), the
83
83
  `BKIT_GH_TOKEN` PAT permission table, and the one-environment-per-repo rationale all
84
84
  live in `.bkit/cloud.md` § Cursor Cloud Agents.
@@ -1,9 +1,5 @@
1
1
  {
2
2
  "mcpServers": {
3
- "linear": {
4
- "type": "http",
5
- "url": "https://mcp.linear.app/mcp"
6
- },
7
3
  "github": {
8
4
  "type": "http",
9
5
  "url": "https://api.githubcopilot.com/mcp/",
@@ -11,6 +7,17 @@
11
7
  "Authorization": "Bearer ${BKIT_GH_TOKEN}",
12
8
  "X-MCP-Toolsets": "context,issues,pull_requests,repos,users,projects,actions"
13
9
  }
10
+ },
11
+ "linear": {
12
+ "type": "http",
13
+ "url": "https://mcp.linear.app/mcp"
14
+ },
15
+ "jira": {
16
+ "type": "http",
17
+ "url": "https://mcp.atlassian.com/v2/mcp",
18
+ "headers": {
19
+ "Authorization": "Bearer ${BKIT_JIRA_API_TOKEN}"
20
+ }
14
21
  }
15
22
  }
16
23
  }
@@ -1,9 +1,5 @@
1
1
  {
2
2
  "mcpServers": {
3
- "linear": {
4
- "type": "http",
5
- "url": "https://mcp.linear.app/mcp"
6
- },
7
3
  "github": {
8
4
  "type": "http",
9
5
  "url": "https://api.githubcopilot.com/mcp/",
@@ -11,6 +7,17 @@
11
7
  "Authorization": "Bearer ${BKIT_GH_TOKEN}",
12
8
  "X-MCP-Toolsets": "context,issues,pull_requests,repos,users,projects,actions"
13
9
  }
10
+ },
11
+ "linear": {
12
+ "type": "http",
13
+ "url": "https://mcp.linear.app/mcp"
14
+ },
15
+ "jira": {
16
+ "type": "http",
17
+ "url": "https://mcp.atlassian.com/v2/mcp",
18
+ "headers": {
19
+ "Authorization": "Bearer ${BKIT_JIRA_API_TOKEN}"
20
+ }
14
21
  }
15
22
  }
16
23
  }
@@ -34,11 +34,13 @@
34
34
  "git checkout -- .*": "ask",
35
35
  "git restore .*": "ask",
36
36
  "git stash drop*": "ask",
37
+ "git stash clear*": "ask",
37
38
  "git rebase -i*": "ask",
38
39
  "gh repo delete*": "ask",
39
40
  "gh pr close*": "ask",
40
41
  "gh release delete*": "ask",
41
42
  "git reset *--hard*": "ask",
43
+ "git -* reset *--hard*": "ask",
42
44
  "git clean -*f*": "ask",
43
45
  "git checkout *.": "ask",
44
46
  "git checkout * . *": "ask",
@@ -53,7 +53,7 @@
53
53
 
54
54
  - A reset rewrites the history every clone, open PR and release record points at, and runs with branch protection off; a revert keeps `main` equal to what was released.
55
55
  - `git revert` on a cross-branch squash (e.g. `feat/*` landed on `main`, not `dev`) can delete files `main` code still references → tree fails CI despite "clean" history. That squash is the step-5 case; production merges MUST come from `dev` (single-feature squash scope).
56
- - On `revert-*` branches pre-push drops only the **unit lane** (`bkit:gate:static` in place of `bkit:gate:static-unit`), so the static lane and the bkit drift gate still run → revert PR pushable when source state transitionally inconsistent.
56
+ - On `revert-*` branches pre-push drops only the **unit and integration lanes** (`bkit:gate:static` in place of the push gate), so the static lane and the bkit drift gate still run → revert PR pushable when source state transitionally inconsistent.
57
57
 
58
58
  ### Post-rollback verification
59
59
 
@@ -117,8 +117,8 @@ Bkit `bkit-ci.yml` recognises tags below. Case-sensitive, literal `[...]` form;
117
117
  <!-- prettier-ignore -->
118
118
  | Tag | Effect | Scope |
119
119
  | --- | --- | --- |
120
- | `[force cache]` | Busts the task-runner cache for the run — recompute instead of replaying cache hits (e.g. turbo: `TURBO_FORCE=1`). Runs the suite even when the SHA already has a green run. Use when investigating suspected ghost-greens. | Read by `Check SHA Cache` and `Detect Direct Push` |
121
- | `[force build]` | The lighter hammer. Exposes `should_force_build=true` + `run_level=full`; does **not** bypass `web_affected`, so no integration / e2e / @live unless web is genuinely affected. Rebuild without paying @live's side effects. Runs the suite even when the SHA already has a green run; deploy steps act on it only when they gate on the output. | Read by `Check SHA Cache` and `Detect Direct Push` |
120
+ | `[force cache]` | Busts the task-runner cache for the run — recompute instead of replaying cache hits (e.g. turbo: `TURBO_FORCE=1`). Runs a pull request's suite even when its files already passed a push run. Use when investigating suspected ghost-greens. | Read by `Check Tree Cache` and `Detect Direct Push` |
121
+ | `[force build]` | The lighter hammer. Exposes `should_force_build=true` + `run_level=full`; does **not** bypass `web_affected`, so no integration / e2e / @live unless web is genuinely affected. Rebuild without paying @live's side effects. Runs a pull request's suite even when its files already passed a push run; deploy steps act on it only when they gate on the output. | Read by `Check Tree Cache` and `Detect Direct Push` |
122
122
  | `[force full]` | The hammer. `run_level=full` **and** it bypasses `web_affected`, so integration, `bkit-tests-e2e-web`, and `bkit-tests-live-web` run on any commit, including docs-only. The E2E spec set does not change, because a PR already runs the full suite. `@live` stays **push-only** (a docs-only `[force full]` push reaches it through the effective `web_affected`; never a PR, never a dispatch). | Read by `Detect Direct Push` step |
123
123
  | `[verbose ci]` | Escalates log detail for one run. Shipped stub flips turbo / Node / Vercel / Supabase / Playwright knobs: `TURBO_LOG_LEVEL=full`, `NODE_OPTIONS=--trace-warnings --trace-deprecation` (a job-level `env:` key, never a `$GITHUB_ENV` write, which the runner rejects while still reporting success), `DEBUG=vercel:*,supabase:*`, plus Playwright `--trace=on` (when E2E stub enabled). Add your stack's equivalents to the same `env:`. Use when `bkit-debug` diagnose returns thin evidence; never for routine pushes (trace.zip files are MB-scale). See `testing.md` for the full knob list and the `--reporter=line` hostile gap. | Read by the job-level `env:` of `bkit-tests-static` (copy the same `env:` onto each lane) |
124
124
  | `[skip ci]` / `[skip actions]` | Honoured natively by GitHub Actions, so it suppresses workflow dispatch entirely. Use sparingly: the suppressed run will not appear in `gh run list`, and downstream `workflow_run` triggers will not fire. | Native GitHub behaviour, not a bkit-level toggle |
@@ -243,6 +243,17 @@ Optional. A same-repo promotion PR into the default branch — head `dev`, or a
243
243
  - Release PR gives up PR-only output (coverage comments, PR-only coverage measurement). None blocks a merge.
244
244
  - Feature → `dev` PRs are unaffected: `pull_request ⇒ run_level=full` (§ Consumer CI contract) still holds there, which is what `/bkit-ship`'s gate relies on.
245
245
 
246
+ ### Pull request tree cache (`Check Tree Cache`)
247
+
248
+ A pull request lane skips its suite when the PR's files already passed that lane in a push run. Push and dispatch runs never skip: the run on a push to `dev` or the default branch is the record of what that branch holds.
249
+
250
+ - **Key = files, not commit.** `scripts/ci/lanes/check-tree-cache.mjs` compares the git tree of the checked-out commit (the PR's merge preview) with the head tree of every green push run in the last 7 days. A commit ID cannot match: a PR run tests a merge commit no push run ever had.
251
+ - **The same lane must have run.** A tree match counts only when that run's job of the same name concluded `success`. A `[skip ci]` / `run_level=none` push concludes green with every lane skipped, which proves nothing.
252
+ - **Bypass:** `[force build]` / `[force cache]` in the PR title.
253
+ - **Fails open to running.** Any `gh` / `git` failure → `skip=false`. A missing script (`scripts/ci/lanes/` not copied) → `skip=false` with a notice.
254
+ - **Capstone:** a skipped lane sets `cache_skip=true`, so `bkit-tests-check` asserts no executed-test count for it.
255
+ - **Needs `actions: read`** on every lane with a job-level `permissions:` block (job-level replaces the workflow-level block).
256
+
246
257
  ## Workflow-file limits GitHub does not enforce visibly
247
258
 
248
259
  **The 21,000-character expression cap.** GitHub compiles every block scalar containing a `${{ … }}` expression as one expression and refuses to compile the workflow past 21,000 characters:
@@ -283,7 +294,7 @@ The merge gate (`bkit runs gate`) asserts the capstone job's `conclusion=success
283
294
  - **A docs-only short-circuit** in the host's build-cancel (Vercel `ignoreCommand` / Netlify) that cancels the run mid-flight → capstone may land `cancelled` (gate code 15) or never complete (code 11).
284
295
  - **A `[skip ci]` token** in a feature-branch commit subject when the PR opens → GitHub suppresses the `pull_request` run entirely; the PR's `statusCheckRollup` is vacuously empty → no run at head (gate code 10).
285
296
 
286
- `bkit runs gate` covers the **common** violation shapes. A skipped non-capstone lane is **reported, not refused**, because the planned-vs-vacuous judgement belongs to the capstone, which takes every lane result as an input and already asserts it per lane. The gate cannot make that judgement itself: the jobs API reports no reason for a skip (a job skipped by a job-level `if:` never reaches a runner, so it carries an empty `steps` array), and a SHA-cache short-circuit concludes `success` with step-level skips plus a `cache_skip` output, never `skipped`.
297
+ `bkit runs gate` covers the **common** violation shapes. A skipped non-capstone lane is **reported, not refused**, because the planned-vs-vacuous judgement belongs to the capstone, which takes every lane result as an input and already asserts it per lane. The gate cannot make that judgement itself: the jobs API reports no reason for a skip (a job skipped by a job-level `if:` never reaches a runner, so it carries an empty `steps` array), and a tree-cache short-circuit concludes `success` with step-level skips plus a `cache_skip` output, never `skipped`.
287
298
 
288
299
  **Code 16 is opt-in, and must stay that way.** It fires only for lanes named in `bkit.shipGateRequiredLanes` (package.json array); the default empty list never refuses. A blanket refuse-on-any-skip is **unsatisfiable by construction** for the CI shape bkit ships: a lane whose `if:` is event-scoped — `bkit-tests-live-web` runs on a push to `dev` or the default branch only — cannot run pre-merge at any head, so a pre-merge gate demanding it refuses every PR forever. Device lanes (`-ios` / `-android`) use the same rule on a pull request and a push; do not treat them as post-merge canaries. Name a lane in `shipGateRequiredLanes` only when your capstone does not assert it and the lane genuinely can run pre-merge. `BKIT_SHIP_GATE_OVERRIDE` remains the audited per-head escape hatch. What still carries the anti-vacuity guarantee is codes 10-15: a run exists, at this head, completed, not cancelled, capstone present, capstone green. Code 14 (green at a superseded head) requires `--branch`: the head-keyed run query is filtered server-side, so a moved head returns the same empty list as a head that never ran, and only a second branch-scoped query separates them. A run that is **present but degraded-but-not-skipped** (e.g. a required lane ran with a reduced test set due to a consumer config the gate cannot see) is a **residual risk named here, not claimed as covered**: the capstone is green because bkit's own `run_level` planner computed `full`; a consumer narrowing inside a lane bkit does not own is invisible to the gate. Keep the capstone (`bkit-tests-check`) as the sole branch-protection required check so `green == validated` survives a docs-only push; do not add per-lane required checks (a hollow lane then green-bars the capstone).
289
300
 
@@ -19,7 +19,7 @@
19
19
 
20
20
  Action SHA-pinning + dependency-update pipeline (Renovate / Dependabot, Trivy scan, CVE handling) → `deployments.md` § Dependency updaters. Here: security invariants only.
21
21
 
22
- **Token isolation:** Renovate PRs get restricted `GITHUB_TOKEN`, no access to cloud lane model-auth secrets (`secrets.ANTHROPIC_API_KEY` / `secrets.OPENCODE_PROVIDER_KEY`); `bkit-cloud.yml` does not dispatch on them. Compromised dependency PR cannot reach agent API credentials.
22
+ **Token isolation:** Renovate PRs get restricted `GITHUB_TOKEN`, no access to cloud lane model-auth secrets (`secrets.ANTHROPIC_API_KEY` / `secrets.OPENCODE_PROVIDER_KEY`) or federated Claude tokens (minted only by a `bkit-cloud.yml` job matching the federation rule); `bkit-cloud.yml` does not dispatch on them. Compromised dependency PR cannot reach agent API credentials.
23
23
 
24
24
  **Scanner isolation:** CI vulnerability scanner (e.g. `bkit-trivy.yml`): `contents: read`, `persist-credentials: false`, no secret; image or action pinned by digest, never a floating tag. Setup → `.bkit/templates.md` § Trivy.
25
25
 
@@ -14,7 +14,7 @@
14
14
  > - Describe current state / rules, not reasons / history; state what to do, not why.
15
15
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
16
  > - Tiers strictly separated — Static · Unit · Integration · E2E · @live · Smoke.
17
- > - Pre-push: `pnpm bkit:gate:static-unit`, then `bkit check`; the `.husky/pre-push` template runs `bkit:gate:static` (no tests) on revert branches / commits. Gate scripts are consumer-owned; bkit's default = typecheck + lint + format:check + prose + slop:delta + `pnpm test` (unit + in-process integration). E2E, @live, service-backed integration excluded (CI — see below). never `--no-verify`.
17
+ > - Pre-push: `pnpm bkit:gate:static-unit-integration` when declared, else `pnpm bkit:gate:static-unit`, then `bkit check`; the `.husky/pre-push` template runs `bkit:gate:static` (no tests) on revert branches / commits. Gate scripts are consumer-owned; bkit's default = typecheck + lint + format:check + prose + slop:delta + `pnpm test` (unit tier only). Integration runs at pre-push once its gate is declared (local services such as a Docker database are fine). E2E, @live and tests against a deployed service excluded (CI — see below). never `--no-verify`.
18
18
 
19
19
  ## CI test tiers (the bkit scaffold)
20
20
 
@@ -393,8 +393,8 @@ Report coverage on each PR **without a paid product or a third-party service**
393
393
  - **Unit = the gate.** Put `coverage.thresholds.branches: <current>` in a `vitest.unit.config.ts` (`mergeConfig` over `vitest.config`) that **only** the unit run loads via `-c`, because **branches** is the meaningful floor (line / statement % overstates confidence); set it to your **current** coverage and ratchet up. vitest coverage is per-**run** (root config), **not** per-project, so `projects` does **not** scope it and a `thresholds` block in `vitest.config` would red **both** runs; the `-c` file is what keeps the gate off integration. A `--coverage.thresholds.branches=<n>` CLI flag also gates, but the report step cannot read it. 80% is convention, not best practice, because a fetishised high bar breeds assertion-free line-touching tests; the executed-≠-exercised rule (§ Validated means executed) matters far more than the number.
394
394
  - **Floor beside the figure.** The unit report step runs on **every** event (a red run too, via `!cancelled()` plus a `hashFiles` guard), passes `vite-config-path: vitest.unit.config.ts`, and comments only on same-repo PRs (`comment-on: pr`, else `none`), so every job summary, pushes included, shows the measured % against its 🎯 floor. The action regex-matches `<metric>: <number>` in that file's raw text: keep the floor on one unquoted line and no other metric name + colon + number in the file, because a broken match drops the target silently while the gate keeps passing.
395
395
  - **Integration = report-only.** Gate integration on **execution** (the capstone's `integration_ran > 0`), **not** a %. A whole-repo integration % is denominator-noise, because integration covers boundaries / flows, not pure logic, and rarely drives every branch, so a hard threshold on it punishes the correct pyramid shape. If you want a real integration %, add `--coverage.include='src/server/**'` on the integration run (same CLI-flag idiom as `--exclude`) to scope it to the integration surface, **then** set a floor, or **ratchet from current** — never a number picked from thin air.
396
- - **Share the unit gate with the build workflow.** Put the unit run (`vitest run -c vitest.unit.config.ts --coverage …`) in a `test:coverage:unit` script and chain it into `bkit:gate:static-unit` — the CI unit lane calls the script, `/bkit-build` Run Tests calls the gate, so the floor has **one source** and a regression fails in the worktree, not only on the PR. Never duplicate the command and sync it by comment, because that drifts. The build runs only the deepest declared `bkit:gate:*`, never the script by name: **left out of the chain, it never gates the build**. (bkit's own repo does exactly this.)
397
- - **Permissions.** The report steps need `pull-requests: write` — declare it at **job level** on the lane that posts. Job-level `permissions:` **replaces** the workflow-level block (not additive), and the SHA-cache step calls `gh run list`, so re-include `actions: read` too or it breaks. **Separate lanes:** with a lane per tier (recommended — see `deployments.md` § Parallel test lanes), each coverage comment posts from its own lane (unit-cov → `bkit-tests-unit`, integration-cov → `bkit-tests-integration`), so put the block on **each** lane that reports. With the combined starter, both live on `bkit-tests-unit`.
396
+ - **Share the unit gate with the build workflow.** Put the unit run (`vitest run -c vitest.unit.config.ts --coverage …`) in a `test:coverage:unit` script and chain it into `bkit:gate:static-unit` in place of `pnpm test`, never beside it (both run every unit test, so each runs twice) — the CI unit lane calls the script, `/bkit-build` Run Tests calls the gate, so the floor has **one source** and a regression fails in the worktree, not only on the PR. Never duplicate the command and sync it by comment, because that drifts. The build runs only the deepest declared `bkit:gate:*`, never the script by name: **left out of the chain, it never gates the build**. (bkit's own repo does exactly this.)
397
+ - **Permissions.** The report steps need `pull-requests: write` — declare it at **job level** on the lane that posts. Job-level `permissions:` **replaces** the workflow-level block (not additive), and the tree-cache step reads runs and jobs, so re-include `actions: read` too or it breaks. **Separate lanes:** with a lane per tier (recommended — see `deployments.md` § Parallel test lanes), each coverage comment posts from its own lane (unit-cov → `bkit-tests-unit`, integration-cov → `bkit-tests-integration`), so put the block on **each** lane that reports. With the combined starter, both live on `bkit-tests-unit`.
398
398
  - **Fork PRs.** `GITHUB_TOKEN` is read-only for PRs from a fork, so commenting fails — the shipped unit step sets `comment-on: none` there (its job summary still lands) and the integration step's `head.repo == repo` guard skips it; adopt the action's `workflow_run` two-workflow pattern if you must comment on fork PRs. The integration step is also guarded on `hashFiles(...)` so a repo with **no integration tier** skips it cleanly.
399
399
  - **Base-branch delta** (▲▼ vs the default branch) is **not** shipped by default, because it needs the base's `coverage-summary.json` (a second run or a stored artifact); wire the action's `json-summary-compare-path` if you want it.
400
400
 
@@ -118,7 +118,7 @@
118
118
  // directly above the pin tells Renovate what to look up. Forms matched:
119
119
  // ARG NODE_VERSION=24.11.0 · GH_VERSION="2.83.0" (Dockerfile / shell)
120
120
  // VALE_VERSION: "3.9.1" · renovate-version: "44.x.y" (workflow env / `with:` input)
121
- // GRAPHIFY_SPEC="graphifyy[sql]==0.9.50" (pip spec in bkit-graphify.sh: value after `==`)
121
+ // GRAPHIFY_SPEC="graphifyy[sql]==0.9.70" (pip spec in bkit-graphify.sh: value after `==`)
122
122
  // npm install -g @opencode/cli@2.0.26 (npm global install)
123
123
  // bash "$RUNNER_TEMP/download-actionlint.bash" 1.7.12 (installer-script version argument)
124
124
  // Pins paired with a checksum (Vale, gh, jq, Node, actionlint) get the new VERSION
@@ -83,41 +83,25 @@ jobs:
83
83
  echo "🔊 [verbose ci] marker active — escalating log detail"
84
84
  echo "DEBUG=vercel:*,supabase:*" >> "$GITHUB_ENV"
85
85
 
86
- # [force build] / [force cache] run the suite even when this SHA already has a green run.
87
- - name: Check SHA Cache
86
+ # Pull requests only: the suite skips when this PR's files already passed a push run
87
+ # (scripts/ci/lanes/check-tree-cache.mjs). A push or dispatch run always runs it, and so
88
+ # does [force build] / [force cache] in the PR title.
89
+ - name: Check Tree Cache
88
90
  id: cache
89
91
  env:
90
92
  GH_TOKEN: ${{ github.token }}
93
+ REPO: ${{ github.repository }}
94
+ EVENT_NAME: ${{ github.event_name }}
95
+ JOB: ${{ github.job }}
91
96
  # User-controlled text (PR title) arrives via env: (runtime expansion,
92
97
  # injection-safe) — never inlined into the run: body.
93
98
  PR_TITLE: ${{ github.event.pull_request.title }}
94
- EVENT_NAME: ${{ github.event_name }}
95
99
  run: |
96
- if [ "$EVENT_NAME" = "pull_request" ]; then
97
- MSG="$PR_TITLE"
98
- else
99
- MSG=$(git log -1 --pretty=%B "$GITHUB_SHA" 2>/dev/null || echo "")
100
- fi
101
- case "$MSG" in
102
- *"[force build]"*|*"[force cache]"*)
103
- echo "skip=false" >> "$GITHUB_OUTPUT"
104
- echo "::notice::force marker present — ignoring SHA cache."
105
- exit 0 ;;
106
- esac
107
- SINCE=$(date -u -d '7 days ago' +%FT%TZ 2>/dev/null || date -u -v -7d +%FT%TZ)
108
- PRIOR=$(gh run list \
109
- --repo "$GITHUB_REPOSITORY" \
110
- --workflow "$GITHUB_WORKFLOW" \
111
- --status success \
112
- --limit 50 \
113
- --json headSha,createdAt \
114
- --jq "[.[] | select(.headSha == \"$GITHUB_SHA\") | select(.createdAt > \"$SINCE\")] | length" \
115
- 2>/dev/null || echo 0)
116
- if [ "${PRIOR:-0}" -gt 0 ]; then
117
- echo "skip=true" >> "$GITHUB_OUTPUT"
118
- echo "::notice::SHA $GITHUB_SHA has $PRIOR prior green run(s) since $SINCE — skipping suite."
100
+ if [ -f scripts/ci/lanes/check-tree-cache.mjs ]; then
101
+ node scripts/ci/lanes/check-tree-cache.mjs >> "$GITHUB_OUTPUT"
119
102
  else
120
103
  echo "skip=false" >> "$GITHUB_OUTPUT"
104
+ echo "::notice::scripts/ci/lanes/check-tree-cache.mjs not copied — running the suite."
121
105
  fi
122
106
 
123
107
  - name: Detect Direct Push
@@ -330,7 +314,7 @@ jobs:
330
314
  # and remote db push move out of this job when you adopt the scaffold below.
331
315
  bkit-tests-unit:
332
316
  runs-on: ubuntu-latest
333
- # bkit-tests-check reads both: cache_skip (a SHA-cache short-circuit asserts no count)
317
+ # bkit-tests-check reads both: cache_skip (a tree-cache short-circuit asserts no count)
334
318
  # and tests_ran (the executed-test count the Run Unit Tests step writes).
335
319
  outputs:
336
320
  cache_skip: ${{ steps.cache.outputs.skip }}
@@ -362,41 +346,25 @@ jobs:
362
346
  echo "🔊 [verbose ci] marker active — escalating log detail"
363
347
  echo "DEBUG=vercel:*,supabase:*" >> "$GITHUB_ENV"
364
348
 
365
- # [force build] / [force cache] run the suite even when this SHA already has a green run.
366
- - name: Check SHA Cache
349
+ # Pull requests only: the suite skips when this PR's files already passed a push run
350
+ # (scripts/ci/lanes/check-tree-cache.mjs). A push or dispatch run always runs it, and so
351
+ # does [force build] / [force cache] in the PR title.
352
+ - name: Check Tree Cache
367
353
  id: cache
368
354
  env:
369
355
  GH_TOKEN: ${{ github.token }}
356
+ REPO: ${{ github.repository }}
357
+ EVENT_NAME: ${{ github.event_name }}
358
+ JOB: ${{ github.job }}
370
359
  # User-controlled text (PR title) arrives via env: (runtime expansion,
371
360
  # injection-safe) — never inlined into the run: body.
372
361
  PR_TITLE: ${{ github.event.pull_request.title }}
373
- EVENT_NAME: ${{ github.event_name }}
374
362
  run: |
375
- if [ "$EVENT_NAME" = "pull_request" ]; then
376
- MSG="$PR_TITLE"
377
- else
378
- MSG=$(git log -1 --pretty=%B "$GITHUB_SHA" 2>/dev/null || echo "")
379
- fi
380
- case "$MSG" in
381
- *"[force build]"*|*"[force cache]"*)
382
- echo "skip=false" >> "$GITHUB_OUTPUT"
383
- echo "::notice::force marker present — ignoring SHA cache."
384
- exit 0 ;;
385
- esac
386
- SINCE=$(date -u -d '7 days ago' +%FT%TZ 2>/dev/null || date -u -v -7d +%FT%TZ)
387
- PRIOR=$(gh run list \
388
- --repo "$GITHUB_REPOSITORY" \
389
- --workflow "$GITHUB_WORKFLOW" \
390
- --status success \
391
- --limit 50 \
392
- --json headSha,createdAt \
393
- --jq "[.[] | select(.headSha == \"$GITHUB_SHA\") | select(.createdAt > \"$SINCE\")] | length" \
394
- 2>/dev/null || echo 0)
395
- if [ "${PRIOR:-0}" -gt 0 ]; then
396
- echo "skip=true" >> "$GITHUB_OUTPUT"
397
- echo "::notice::SHA $GITHUB_SHA has $PRIOR prior green run(s) since $SINCE — skipping suite."
363
+ if [ -f scripts/ci/lanes/check-tree-cache.mjs ]; then
364
+ node scripts/ci/lanes/check-tree-cache.mjs >> "$GITHUB_OUTPUT"
398
365
  else
399
366
  echo "skip=false" >> "$GITHUB_OUTPUT"
367
+ echo "::notice::scripts/ci/lanes/check-tree-cache.mjs not copied — running the suite."
400
368
  fi
401
369
 
402
370
  - name: Detect Direct Push
@@ -543,7 +511,7 @@ jobs:
543
511
  # (a CLI flag on the integration run, same idiom as --exclude above) to scope it to the integration
544
512
  # surface THEN set a floor, or ratchet from current — never a picked number. See docs/testing.md § Coverage on PRs.
545
513
  # 4. JOB-LEVEL permissions on bkit-tests-unit. Job-level REPLACES the workflow-level block (not additive), and the
546
- # Check SHA Cache step calls `gh run list`, so you MUST re-include actions: read or the cache step breaks:
514
+ # Check Tree Cache step reads runs and jobs, so you MUST re-include actions: read or the cache step breaks:
547
515
  # permissions:
548
516
  # actions: read
549
517
  # contents: read