@cbartens/bkit 5.4.0 → 5.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +19 -7
- package/.bkit/core/.agents/rules.md +24 -9
- package/.bkit/core/.bkit/README.md +18 -6
- package/.bkit/core/.bkit/cloud.md +46 -15
- package/.bkit/core/.bkit/comparison.md +2 -2
- package/.bkit/core/.bkit/install.md +19 -18
- package/.bkit/core/.bkit/pipeline.md +3 -1
- package/.bkit/core/.bkit/prompts.md +38 -20
- package/.bkit/core/.bkit/providers.md +6 -6
- package/.bkit/core/.bkit/templates.md +44 -13
- package/.bkit/core/.bkit/trackers.md +99 -35
- package/.bkit/core/.bkit/workflows.md +50 -45
- package/.bkit/core/AGENTS.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-issues.md +22 -6
- package/.bkit/core/engine/checks/after/auth.ts +88 -45
- package/.bkit/core/engine/checks/after/ci-yml.ts +0 -1
- package/.bkit/core/engine/checks/after/github.ts +42 -78
- package/.bkit/core/engine/checks/after/index.ts +1 -6
- package/.bkit/core/engine/checks/after/tools.ts +1 -1
- package/.bkit/core/engine/checks/before/env.ts +28 -18
- package/.bkit/core/engine/checks/before/mcp.ts +4 -2
- package/.bkit/core/engine/checks/tips/catalogue.ts +15 -2
- package/.bkit/core/engine/checks/tips/index.ts +5 -2
- package/.bkit/core/engine/cli.ts +7 -5
- package/.bkit/core/engine/commands/ci/ci.ts +107 -0
- package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
- package/.bkit/core/engine/commands/workflow/issues.ts +61 -63
- package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
- package/.bkit/core/engine/commands/workflow/prs.ts +3 -1
- package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +5 -1
- package/.bkit/core/engine/commands/workflow/steps.ts +2 -2
- package/.bkit/core/engine/commands/workflow/workflows.ts +9 -4
- package/.bkit/core/engine/commands/workflow/worktrees.ts +91 -14
- package/.bkit/core/engine/install/manifest.ts +31 -10
- package/.bkit/core/engine/install/modules/cloud.ts +3 -1
- package/.bkit/core/engine/install/modules/core.ts +153 -4
- package/.bkit/core/engine/install/modules/opencode.ts +5 -0
- package/.bkit/core/engine/install/write.ts +37 -1
- package/.bkit/core/engine/render/trackers.ts +35 -23
- package/.bkit/core/engine/shared/egress.ts +6 -0
- package/.bkit/core/engine/shared/settings.ts +130 -11
- package/.bkit/core/hooks/guardrails-tiers.js +1 -1
- package/.bkit/core/prompts/bkit-audit-generate.md +42 -12
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -0
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
- package/.bkit/core/prompts/bkit-design-generate.md +4 -1
- package/.bkit/core/prompts/bkit-plan-generate.md +5 -3
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
- package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
- package/.bkit/core/prompts/bkit-utility-update-failures.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
- package/.bkit/core/workflows/bkit-auto.md +19 -6
- package/.bkit/core/workflows/bkit-build.md +59 -17
- package/.bkit/core/workflows/bkit-debug.md +64 -20
- package/.bkit/core/workflows/bkit-design.md +83 -28
- package/.bkit/core/workflows/bkit-plan.md +61 -20
- package/.bkit/core/workflows/bkit-ship.md +48 -18
- package/.bkit/shared/.bkit/.env.example +8 -0
- package/.bkit/shared/.claude/settings.json +3 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
- package/.bkit/shared/.cursor/mcp.json +11 -4
- package/.bkit/shared/.mcp.json +11 -4
- package/.bkit/shared/.opencode/opencode.json +2 -0
- package/.bkit/shared/docs/deployments.md +6 -7
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/testing.md +13 -5
- package/.bkit/templates/.github/renovate.json5 +1 -1
- package/.bkit/templates/.github/workflows/bkit-ci.yml +21 -115
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
- package/.bkit/templates/.husky/pre-commit +4 -4
- package/.bkit/templates/.husky/pre-push +107 -18
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
- package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
- package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
- package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
- package/CHANGELOG.md +67 -1
- package/README.md +16 -6
- package/dist/checks/after/auth.js +81 -45
- package/dist/checks/after/ci-yml.js +0 -1
- package/dist/checks/after/github.js +41 -76
- package/dist/checks/after/index.js +2 -7
- package/dist/checks/after/tools.js +1 -1
- package/dist/checks/before/env.js +24 -17
- package/dist/checks/before/mcp.js +4 -2
- package/dist/checks/tips/catalogue.js +14 -2
- package/dist/checks/tips/index.js +4 -2
- package/dist/cli.js +7 -5
- package/dist/commands/ci/ci.js +100 -0
- package/dist/commands/install/uninstall.js +42 -0
- package/dist/commands/workflow/fids.js +22 -15
- package/dist/commands/workflow/issues.js +53 -61
- package/dist/commands/workflow/ledgers.js +26 -11
- package/dist/commands/workflow/prs.js +3 -1
- package/dist/commands/workflow/repo.js +6 -0
- package/dist/commands/workflow/roadmap.js +3 -1
- package/dist/commands/workflow/steps.js +2 -2
- package/dist/commands/workflow/workflows.js +9 -4
- package/dist/commands/workflow/worktrees.js +74 -13
- package/dist/install/manifest.js +30 -10
- package/dist/install/modules/cloud.js +3 -1
- package/dist/install/modules/core.js +157 -5
- package/dist/install/modules/opencode.js +6 -0
- package/dist/install/write.js +26 -2
- package/dist/render/trackers.js +34 -20
- package/dist/shared/egress.js +6 -0
- package/dist/shared/settings.js +59 -7
- package/package.json +14 -3
|
@@ -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` (
|
|
32
|
-
> - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive
|
|
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.
|
|
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`); board status sync needs `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) and `package.json` `bkit.github.project`, 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` (
|
|
39
|
-
> - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive
|
|
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`
|
|
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}",
|
|
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
|
|
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=""
|
|
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
|
|
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)` →
|
|
189
|
+
**If** `BOARD` = null → log `boardSkipped` → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → set status `mcp__github__projects_write({BOARD}.updateItem)`.
|
|
171
190
|
<!-- bkit:tracker github end -->
|
|
172
191
|
<!-- bkit:tracker linear start -->
|
|
173
|
-
`mcp__linear__save_issue({ id: "{ISSUE_ID}",
|
|
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)` →
|
|
634
|
+
**If** `BOARD` = null → log `boardSkipped` → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → set status `mcp__github__projects_write({BOARD}.updateItem)`.
|
|
610
635
|
<!-- bkit:tracker github end -->
|
|
611
636
|
<!-- bkit:tracker linear start -->
|
|
612
|
-
`mcp__linear__save_issue({ id: "{ISSUE_ID}",
|
|
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
|
|
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
|
-
- `
|
|
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
|
|
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
|
}
|
package/.bkit/shared/.mcp.json
CHANGED
|
@@ -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
|
|
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`).
|
|
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.
|
|
120
|
+
| `[force cache]` | Busts the task-runner cache for the run — recompute instead of replaying cache hits (e.g. turbo: `TURBO_FORCE=1`). Use when investigating suspected ghost-greens. | Read by `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. Deploy steps act on it only when they gate on the output. | Read by `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 |
|
|
@@ -151,7 +151,7 @@ Bkit ships a **mostly flat, wide** scaffold: `bkit-tests-scope` (always-on; read
|
|
|
151
151
|
<!-- prettier-ignore -->
|
|
152
152
|
| Run level | When | Runs | Defers |
|
|
153
153
|
| --- | --- | --- | --- |
|
|
154
|
-
| `none` | `[skip ci]` / `[skip actions]
|
|
154
|
+
| `none` | `[skip ci]` / `[skip actions]`; or release-PR mirror mode (the capstone copies the `dev` push run — § One CI run per dev commit). | Planner, then stop. | Every test lane. |
|
|
155
155
|
| `partial` | Push to `dev` that came from a merged PR, and no `[force build]` / `[force full]`. | Static, unit, integration when `web_affected`, build lanes, migration. `@live` (`bkit-tests-live-web`) still runs on this push when `web_affected`. | `bkit-tests-e2e-web`. Deploy (not the default branch). |
|
|
156
156
|
| `full` | Pull request; `workflow_dispatch`; push to `{{DEFAULT_BRANCH}}`; direct push to `dev` (no merged PR); `[force build]` / `[force full]`. | Partial's lanes, plus `bkit-tests-e2e-web` when `web_affected`. Same spec set as a push (`testing.md` § E2E on PRs). | `@live` off a PR and off a dispatch. On a default-branch push, `bkit-tests-deploy` promotes **before** the E2E / `@live` lanes run; it is not required, and its own `concurrency:` group stops two releases overlapping. Health runs as `workflow_run` after CI. |
|
|
157
157
|
|
|
@@ -168,11 +168,10 @@ A newer run cancels the older one on every event **except the default branch, wh
|
|
|
168
168
|
|
|
169
169
|
A push diffs against the head of the last successful CI run on that branch, not `github.event.before`. Fall back to `github.event.before` only when there is no such run or it is no longer an ancestor. A `workflow_dispatch` has no base commit: short-circuit the affected step to fully affected. `HEAD~1` is only for the delta gates on a dispatch. Markers are inert on dispatch; steer with inputs (§ Commit-message force tags). The planner parses markers once; every lane reads `plan.markers_present`. The only re-read of the commit or PR text is the workflow-level task-runner cache bust (e.g. `TURBO_FORCE`). Plan JSON: validate with `has()` / `!= null`. jq `//` treats `false` as absent and drops a real `run_live: false`.
|
|
170
170
|
|
|
171
|
-
Migration-immutability and slop-delta run on every event against that same base. The starter's copies of those steps are still `pull_request`-only; that `if:` is the pre-planner shape. Point them at the planner base once `bkit-tests-scope` exists.
|
|
171
|
+
Migration-immutability and slop-delta run on every event against that same base. The starter's copies of those steps are still `pull_request`-only; that `if:` is the pre-planner shape. Point them at the planner base once `bkit-tests-scope` exists. Pre-push on a `dev` push resolves the same base (`resolve-push-base.mjs --local`, `.bkit/templates.md` § Git hooks) and exports it as `SLOP_BASE_REF`; a repo-owned migration-immutability pre-push check reads that variable too.
|
|
172
172
|
|
|
173
173
|
Composition guidance:
|
|
174
174
|
|
|
175
|
-
- `cache.outputs.skip` = `none` gate — every step: `if: steps.cache.outputs.skip != 'true'`.
|
|
176
175
|
- `steps.detect.outputs.should_force_build` / `should_run_full` = escalation into `full`.
|
|
177
176
|
- No merged PR on `dev` push (auto cache bust, e.g. `TURBO_FORCE=1`) = recovery signal — partial CI with cache busted.
|
|
178
177
|
- Health (or smoke, when the probe is a script rather than a health URL): separate workflow, `workflow_run` after CI success — not a required check. One of the two, unless the probes differ (§ Smoke trigger plumbing).
|
|
@@ -283,7 +282,7 @@ The merge gate (`bkit runs gate`) asserts the capstone job's `conclusion=success
|
|
|
283
282
|
- **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
283
|
- **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
284
|
|
|
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)
|
|
285
|
+
`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).
|
|
287
286
|
|
|
288
287
|
**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
288
|
|
|
@@ -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
|
|
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
|
|
|
@@ -364,7 +364,15 @@ A tier that needs a stateful backing service (database, cache, queue, search ind
|
|
|
364
364
|
|
|
365
365
|
bkit's `bkit-tests-migration` lane (`bkit-stub:bkit-tests-migration`) is the ready-made home: **always-on** (no job-level `if:` because e2e / live `needs:` it for remote-push ordering; a skip cascades). Replay + seed assert stay plan- / path-gated per-step. On every push to `dev`/`main` the same lane owns remote apply of new migrations (e.g. `supabase db push --linked --include-all`) (un-gated by `run_migration` so it self-heals; after replay so from-empty failure never reaches remote). Capstone asserts `result == success` whenever scope succeeded. Fold into `bkit-tests-check`'s `needs:`.
|
|
366
366
|
|
|
367
|
-
**Local integration freshness.** If your local stack reuses a warm data volume (e.g. Docker + `supabase start`), a bare start can leave migrations unapplied (stale-volume footgun). Prefer a reset-by-default runner over a bare integration run (e.g. `turbo run test:integration`) — mirror local E2E: reset unless `--no-reset`. Shape: `pnpm test:integration:local` → script that starts local stack,
|
|
367
|
+
**Local integration freshness.** If your local stack reuses a warm data volume (e.g. Docker + `supabase start`), a bare start can leave migrations unapplied (stale-volume footgun). Prefer a reset-by-default runner over a bare integration run (e.g. `turbo run test:integration`) — mirror local E2E: reset unless `--no-reset`. Shape: `pnpm test:integration:local` → script that starts local stack, exports its URL + keys, resets from empty (e.g. `supabase db reset --local`), then runs integration (CI passthrough, because CI boots its own hermetic stack).
|
|
368
|
+
|
|
369
|
+
**Local runners never touch env files** (e.g. `.env.local`, `.env.production`; may be the only copy of live credentials):
|
|
370
|
+
|
|
371
|
+
- Target local stack by exporting its values before config loads; loaders (Next, dotenv `override: false`) never override a set key.
|
|
372
|
+
- Blank a hosted key with `export KEY=""`, never `unset` (loader refills unset keys from the file).
|
|
373
|
+
- Never delete, move or hide-and-restore the file (a killed run loses it).
|
|
374
|
+
- Never `vercel env pull` onto it (replaces it with the host's keys only); pull to a scratch file, copy keys across.
|
|
375
|
+
- Guard test fails any tracked script that deletes, moves or overwrites an env file.
|
|
368
376
|
|
|
369
377
|
**"Fresh" means replay-from-empty, not a reused volume.** A bare "start the local stack" command often **reuses an existing data volume** and applies only what's missing, so a "fresh" start can silently run a months-old schema while reporting success. Only a reset / replay from an **empty** store is a freshness proof. And a green replay is not a green **seed**: assert the seed actually loaded (a known row exists), because the reset can exit 0 while a conditional insert no-ops or the seed aborts mid-file (§ Migration-replay + seed carries the full seed-determinism rules).
|
|
370
378
|
|
|
@@ -393,8 +401,8 @@ Report coverage on each PR **without a paid product or a third-party service**
|
|
|
393
401
|
- **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
402
|
- **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
403
|
- **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),
|
|
404
|
+
- **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.)
|
|
405
|
+
- **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), so re-include `contents: read` too or the checkout 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
406
|
- **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
407
|
- **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
408
|
|
|
@@ -406,7 +414,7 @@ The **E2E tier** (`bkit-stub:e2e-coverage`) reports Playwright coverage the same
|
|
|
406
414
|
- **Report with Monocart.** `monocart-coverage-reports` (wired via the `monocart-reporter` Playwright reporter) ingests **either** V8 or Istanbul input and emits Istanbul-format `coverage/e2e/coverage-summary.json` + `coverage-final.json` — the **same two files** the vitest action reads (`reports: ['json-summary', 'json', 'lcov']`), so no new commenter is needed.
|
|
407
415
|
- **Comment by reuse.** Point `davelosert/vitest-coverage-report-action@v2` at `coverage/e2e` with `name: e2e`. If Monocart's `coverage-final.json` isn't accepted for `file-coverage-mode: changes`, drop to `file-coverage-mode: all`, or comment via a cobertura action (`irongut/CodeCoverageSummary`) on Monocart's `cobertura` report.
|
|
408
416
|
- **Report-only — no threshold by default.** A whole-app E2E % is denominator-noise (E2E exercises user **flows**, not every branch), so gate the tier on the **E2E step succeeding**, not a number. For a real E2E %, scope Monocart's `entryFilter`/`sourceFilter` to the surface E2E is meant to cover, **then** ratchet from current — never a picked number.
|
|
409
|
-
- **Permissions / forks.** The E2E coverage report runs in the **`bkit-tests-e2e-web` lane** (or, with the combined starter, in `bkit-tests-unit`), and needs that lane's job-level `pull-requests: write` + `
|
|
417
|
+
- **Permissions / forks.** The E2E coverage report runs in the **`bkit-tests-e2e-web` lane** (or, with the combined starter, in `bkit-tests-unit`), and needs that lane's job-level `pull-requests: write` + `contents: read` block, or the comment can't post. The `head.repo == repo` guard skips fork PRs; a `hashFiles('coverage/e2e/coverage-summary.json')` guard skips repos with no E2E coverage.
|
|
410
418
|
|
|
411
419
|
## CI verbosity (`[verbose ci]`)
|
|
412
420
|
|
|
@@ -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.
|
|
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
|