@cbartens/bkit 5.3.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.
- package/.bkit/README.md +20 -7
- package/.bkit/core/.agents/docs.md +1 -1
- package/.bkit/core/.agents/rules.md +14 -9
- package/.bkit/core/.bkit/README.md +19 -6
- package/.bkit/core/.bkit/cloud.md +77 -46
- package/.bkit/core/.bkit/comparison.md +3 -3
- package/.bkit/core/.bkit/install.md +21 -18
- package/.bkit/core/.bkit/lite.md +6 -6
- package/.bkit/core/.bkit/pipeline.md +6 -3
- package/.bkit/core/.bkit/prompts.md +14 -10
- package/.bkit/core/.bkit/providers.md +7 -7
- package/.bkit/core/.bkit/templates.md +46 -10
- package/.bkit/core/.bkit/trackers.md +92 -38
- package/.bkit/core/.bkit/workflows.md +140 -116
- package/.bkit/core/AGENTS.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-issues.md +25 -8
- package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
- package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/engine/checks/after/auth.ts +88 -45
- package/.bkit/core/engine/checks/after/github.ts +18 -5
- package/.bkit/core/engine/checks/after/index.ts +1 -1
- 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/status-holes.ts +0 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +31 -2
- package/.bkit/core/engine/checks/tips/index.ts +49 -27
- package/.bkit/core/engine/cli.ts +27 -18
- package/.bkit/core/engine/commands/ci/ci.ts +107 -0
- package/.bkit/core/engine/commands/comply.ts +25 -16
- package/.bkit/core/engine/commands/install/install.ts +11 -4
- package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
- package/.bkit/core/engine/commands/land.ts +156 -0
- package/.bkit/core/engine/commands/lib.ts +10 -8
- package/.bkit/core/engine/commands/registry.ts +2 -0
- package/.bkit/core/engine/commands/tips.ts +7 -3
- package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
- package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
- package/.bkit/core/engine/commands/workflow/issues.ts +106 -42
- package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
- package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
- package/.bkit/core/engine/commands/workflow/prs.ts +14 -3
- package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +53 -54
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
- package/.bkit/core/engine/commands/workflow/status.ts +33 -11
- package/.bkit/core/engine/commands/workflow/steps.ts +26 -17
- package/.bkit/core/engine/commands/workflow/workflows.ts +442 -269
- package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
- package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
- 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 +97 -4
- package/.bkit/core/engine/install/modules/opencode.ts +5 -0
- package/.bkit/core/engine/install/placeholders.ts +13 -17
- 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 +96 -1
- package/.bkit/core/engine/shared/timeouts.ts +8 -7
- package/.bkit/core/hooks/guardrails-tiers.js +1 -1
- package/.bkit/core/prompts/bkit-audit-generate.md +80 -7
- 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-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 +2 -1
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
- package/.bkit/core/prompts/bkit-utility-update-failures.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +12 -5
- 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 +64 -22
- package/.bkit/core/workflows/bkit-debug.md +72 -28
- package/.bkit/core/workflows/bkit-design.md +101 -37
- package/.bkit/core/workflows/bkit-plan.md +82 -31
- package/.bkit/core/workflows/bkit-ship.md +127 -108
- package/.bkit/shared/.bkit/.env.example +8 -0
- package/.bkit/shared/.claude/bkit-cloud.md +12 -12
- package/.bkit/shared/.claude/settings.json +4 -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 +44 -29
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/testing.md +3 -3
- package/.bkit/shared/gitignore +1 -2
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
- package/.bkit/templates/.github/renovate.json5 +1 -1
- package/.bkit/templates/.github/workflows/bkit-ci.yml +29 -56
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
- package/.bkit/templates/.husky/pre-commit +10 -4
- package/.bkit/templates/.husky/pre-push +69 -12
- package/.bkit/templates/.lintstagedrc.json +5 -1
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
- package/CHANGELOG.md +85 -1
- package/README.md +102 -100
- package/dist/checks/after/auth.js +81 -45
- package/dist/checks/after/github.js +17 -5
- package/dist/checks/after/index.js +1 -1
- 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/status-holes.js +0 -1
- package/dist/checks/tips/catalogue.js +28 -2
- package/dist/checks/tips/index.js +44 -28
- package/dist/cli.js +27 -19
- package/dist/commands/ci/ci.js +100 -0
- package/dist/commands/comply.js +20 -13
- package/dist/commands/install/install.js +10 -4
- package/dist/commands/install/uninstall.js +42 -0
- package/dist/commands/land.js +129 -0
- package/dist/commands/lib.js +9 -6
- package/dist/commands/registry.js +2 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +300 -243
- package/dist/commands/workflow/disk.js +452 -0
- package/dist/commands/workflow/fids.js +22 -15
- package/dist/commands/workflow/issues.js +90 -41
- package/dist/commands/workflow/ledgers.js +26 -11
- package/dist/commands/workflow/locks.js +35 -130
- package/dist/commands/workflow/prs.js +8 -3
- package/dist/commands/workflow/repo.js +5 -0
- package/dist/commands/workflow/roadmap.js +52 -57
- package/dist/commands/workflow/runtime.js +3 -2
- package/dist/commands/workflow/status.js +32 -12
- package/dist/commands/workflow/steps.js +20 -13
- package/dist/commands/workflow/workflows.js +397 -251
- package/dist/commands/workflow/workstreams.js +3 -2
- package/dist/commands/workflow/worktrees.js +11 -1
- package/dist/install/manifest.js +30 -10
- package/dist/install/modules/cloud.js +3 -1
- package/dist/install/modules/core.js +95 -5
- package/dist/install/modules/opencode.js +6 -0
- package/dist/install/placeholders.js +13 -19
- 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 +44 -0
- package/dist/shared/timeouts.js +8 -7
- package/package.json +11 -2
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",
|
|
@@ -17,50 +17,50 @@
|
|
|
17
17
|
|
|
18
18
|
## Production rollback runbook
|
|
19
19
|
|
|
20
|
-
> Bad
|
|
20
|
+
> Bad release live → move production back to the last good deployment, then fix forward through `dev`. Production moves first; `main` keeps its history. Steps are host-agnostic; commands = Vercel example.
|
|
21
21
|
|
|
22
22
|
### Preconditions
|
|
23
23
|
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
- `jq` installed (`brew install jq` / system package manager).
|
|
24
|
+
- Last good deployment id: the one production served before the bad release (`bkit-tests-deploy` logs it as the deployment it replaced), else the host's deployment for a commit green on `main` (`gh run list --branch main --status success --limit 5`).
|
|
25
|
+
- `gh auth status` green.
|
|
27
26
|
|
|
28
27
|
### Playbook
|
|
29
28
|
|
|
30
|
-
1. **
|
|
29
|
+
1. **Move production back** to the last good deployment. No rebuild, no git change. Move every production host the release moved (site, webhook / background-job aliases), never the website alone. With `bkit-tests-deploy` adopted, run the switch from a `workflow_dispatch` rollback workflow in the deploy job's `concurrency:` group (`cancel-in-progress: false`), so a release and a rollback never switch production at once. e.g. Vercel:
|
|
31
30
|
```bash
|
|
32
|
-
|
|
31
|
+
vercel ls --meta githubCommitSha=<green-sha>
|
|
32
|
+
vercel promote <prior-deployment-url>
|
|
33
33
|
```
|
|
34
|
-
2. **
|
|
34
|
+
2. **Mark the bad deployment** (`bkit-tests-deploy` adopted). `bkit-tests-deploy` refuses the deployment id in repo variable `ROLLED_BACK_DEPLOYMENT_ID` (§ Promote before the lanes), so a "Re-run all jobs" of the bad run cannot promote it again.
|
|
35
35
|
```bash
|
|
36
|
-
gh
|
|
36
|
+
gh variable set ROLLED_BACK_DEPLOYMENT_ID --body <bad-deployment-id>
|
|
37
37
|
```
|
|
38
|
-
3. **
|
|
38
|
+
3. **Verify** — § Post-rollback verification.
|
|
39
|
+
4. **Fix forward through `dev`.** Revert the bad change on a `revert-*` branch off `dev` (or ship the fix), PR into `dev`, release `dev` → `main` as usual. Hold every other release PR into `main` until it carries the fix, because a release cut from `main`'s tip ships the bad commit again. The release descends from the commit production serves, so `bkit-tests-deploy` promotes it. Database: never rewound or re-seeded; ship a corrective migration (§ Applying migrations at deploy time). The rolled-back build must work on the newer schema (expand first, contract later).
|
|
40
|
+
5. **Reset `main` — last resort**, only when `main` holds commits a `dev` release cannot undo (e.g. a squash that landed on `main` without going through `dev`), and only after step 1. Reset first and `bkit-tests-deploy` refuses every release, the run the reset starts included, until production moves: production's commit is no longer an ancestor of `main`. The reset is a push to `main`: with `bkit-tests-deploy` it starts a release run that builds and promotes a fresh deployment of `<green-sha>`. Needs `jq`, local repo on `main`, clean tree.
|
|
39
41
|
```bash
|
|
42
|
+
# save protection verbatim (GET and PUT shapes differ; raw GET avoids hand-mapping)
|
|
43
|
+
gh api repos/{OWNER}/{REPO}/branches/main/protection > /tmp/main-protection.json
|
|
44
|
+
# disable protection so the force-reset is accepted
|
|
45
|
+
gh api -X DELETE repos/{OWNER}/{REPO}/branches/main/protection
|
|
46
|
+
# force-reset the ref
|
|
40
47
|
gh api -X PATCH repos/{OWNER}/{REPO}/git/refs/heads/main -f sha=<green-sha> -F force=true
|
|
41
|
-
|
|
42
|
-
4. **Restore protection** from saved JSON. GET → PUT shape mismatch: `required-status-checks` → `required_status_checks`, contexts list, etc. Inspect saved JSON; PUT equivalent shape.
|
|
43
|
-
```bash
|
|
48
|
+
# restore: inspect the saved JSON and PUT the equivalent shape (`required-status-checks` → `required_status_checks`, contexts list, etc.)
|
|
44
49
|
gh api -X PUT repos/{OWNER}/{REPO}/branches/main/protection --input /tmp/main-protection.json
|
|
45
50
|
```
|
|
46
|
-
5. **Re-point production deployment** at the host. A host that aliases production to its latest build does not auto-rollback on git ref rewrites, so the alias stays on most-recent push until manually promoted. Look up prior good deployment by commit SHA and promote it. e.g. Vercel:
|
|
47
|
-
```bash
|
|
48
|
-
vercel ls --meta githubCommitSha=<green-sha>
|
|
49
|
-
vercel promote <prior-deployment-url>
|
|
50
|
-
```
|
|
51
|
-
Without this step: git ref rolled back but production still serves bad build.
|
|
52
51
|
|
|
53
|
-
###
|
|
52
|
+
### Revert, not reset
|
|
54
53
|
|
|
55
|
-
-
|
|
56
|
-
- `feat
|
|
57
|
-
- On `revert-*` branches pre-push drops only the **unit
|
|
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
|
+
- `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 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.
|
|
58
57
|
|
|
59
58
|
### Post-rollback verification
|
|
60
59
|
|
|
61
|
-
-
|
|
62
|
-
- `curl -sI https://{prod-alias}` headers report the rolled-back deployment id.
|
|
60
|
+
- Every production host reports the last good deployment id (host API read-back, or `curl -sI https://{prod-alias}` headers).
|
|
63
61
|
- Run the production smoke suite to confirm the rolled-back app behaves as expected.
|
|
62
|
+
- `bkit-tests-deploy` adopted: `gh variable get ROLLED_BACK_DEPLOYMENT_ID` prints the bad deployment id.
|
|
63
|
+
- After a step-5 reset: `gh api repos/{OWNER}/{REPO}/git/refs/heads/main --jq .object.sha` equals the green SHA.
|
|
64
64
|
|
|
65
65
|
## Dev rollback runbook
|
|
66
66
|
|
|
@@ -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
|
|
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
|
|
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 |
|
|
@@ -137,7 +137,7 @@ Direct push to `dev` (no merged PR ancestry) auto-busts the task-runner cache (e
|
|
|
137
137
|
|
|
138
138
|
## Autonomous phase-close prerequisites
|
|
139
139
|
|
|
140
|
-
Design / plan Close Workflow lands docs on `dev` two ways.
|
|
140
|
+
Design / plan Close Workflow lands docs on `dev` two ways. Every runtime first builds the close commit off `origin/dev` and pushes it straight to `dev`: when that push goes through, **no repo setting is required, and no PR is created**. When GitHub refuses it (branch protection or a ruleset on `dev`) the close opens a PR and squash-merges it, which adds two repo prerequisites. Neither is pre-flighted, because no admin-scope token is required; the dependency asserts itself by the close's own merge failing loudly.
|
|
141
141
|
|
|
142
142
|
- **Branch protection on `dev` permits the autonomous merge**, because no human review is required. The PR-path merge does **not** wait for checks: its merge subject carries `bkit [skip ci]`, so a docs-only close dispatches no run to wait for. A rule requiring status checks to pass will block it.
|
|
143
143
|
- **"Automatically delete head branches" is enabled** (repo Settings → General). The PR-path close deliberately does not pass `--delete-branch`, because `gh` also deletes the local branch, which fails when that branch is checked out in a worktree and returns non-zero after a successful merge. Head-branch cleanup relies on the repo setting instead.
|
|
@@ -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
|
|
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
|
|
|
@@ -300,7 +311,7 @@ To unwind a bad ship surface (the gate command, managed config, or rewritten `bk
|
|
|
300
311
|
3. **Audit any `BKIT_SHIP_GATE_OVERRIDE` rows** in `docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` written in the interim. Each `type:"ship-gate-override"` row is a sanctioned escape that turned a refusal into a merge; treat every row as a PR whose capstone was not green at the merged head and re-verify it against the pinned-good gate (`bkit runs gate --head=<sha>`). `[bkit-runs] override honoured for head …` is the matching `docs/observability.md` grep key.
|
|
301
312
|
4. **No per-workflow pin / revert exists**; the package pin + selective `bkit upgrade` hold is the recovery path. Document any incident in `docs/failures.jsonl`.
|
|
302
313
|
|
|
303
|
-
Ship's docs sync, summaries, `SHIPPED` roadmap row and skill removals ride the PR: one `[skip ci]` commit on the feature branch before the merge — the only pre-merge push besides conflict-resolve. Status rows (`status.jsonl`) →
|
|
314
|
+
Ship's docs sync, summaries, `SHIPPED` roadmap row and skill removals ride the PR: one `[skip ci]` commit on the feature branch before the merge — the only pre-merge push besides conflict-resolve. Status rows (`status.jsonl`) → the feature worktree's tree on every runtime (`BOOK_ROOT` = `{WORKTREE_PATH}`; ship never checks out `dev`); see `.bkit/workflows.md` § `status.jsonl` — workflow state SoT. Post-merge tail = one `[skip ci]` close commit built in a throwaway checkout of `origin/dev` carrying the book → push `dev` (`dev` moved → rebuilt, pushed again), refused → `ship-close/{FID}` PR.
|
|
304
315
|
|
|
305
316
|
## Smoke trigger plumbing
|
|
306
317
|
|
|
@@ -340,6 +351,8 @@ Latent until the first build-time DB read lands, so flag it in review when one i
|
|
|
340
351
|
|
|
341
352
|
With `bkit-tests-deploy` adopted, the host does not auto-build the default branch. `bkit-tests-build-web` creates this SHA's deployment, polls it to ready, and publishes `deployment_url` + `deployment_id`; the production alias still serves the previous release. `bkit-tests-deploy` `needs: [bkit-tests-migration, bkit-tests-build-web]`, runs on a push to the default branch only, and is not a required check. It promotes the exact `deployment_id` the build lane published — it does not look the deployment up again by SHA — and a `409` is success only when the body says this id is already current production. On `{{DEFAULT_BRANCH}}` it runs **before** the E2E / `@live` lanes: each of those `needs:` it and starts by proving production serves this run's build (by deployment id), so a re-run after a rollback refuses instead of testing the old build and going green. A red deploy job means the release did not happen; production still serves the previous deployment.
|
|
342
353
|
|
|
354
|
+
Before it promotes, the job refuses, moving nothing, when the deployment id equals repo variable `ROLLED_BACK_DEPLOYMENT_ID` (§ Production rollback runbook step 2), or when this commit is neither the commit production serves nor a descendant of it (e.g. GitHub's compare API `<production-sha>...<this-sha>` status other than `ahead` / `identical`). A re-run of an old run then cannot move production back to an older release. Production unreadable, or its deployment recording no commit → refuse. Same commit → promote (idempotent re-run).
|
|
355
|
+
|
|
343
356
|
Two guards keep a release honest: the deploy job carries its own `concurrency:` group (`cancel-in-progress: false`, so two releases never overlap), and the workflow-level block queues on `{{DEFAULT_BRANCH}}` (§ One run per branch or pull request) so a newer push waits rather than cancelling a switch in flight. `bkit-tests-migration` waits for static / unit / integration / `build-web` before it touches production's database.
|
|
344
357
|
|
|
345
358
|
Do not add a host-side "hold promotion until a named check passes" setting (e.g. Vercel Deployment Checks). That list stays empty. This job is the promotion. e.g. Vercel: `git.deploymentEnabled` for the default branch is false; auto-assign of production domains is off.
|
|
@@ -413,6 +426,8 @@ Use one. Both open PRs for the same packages. `bkit.depUpdater: "none"` skips th
|
|
|
413
426
|
|
|
414
427
|
**Pins outside package files.** The `customManagers` entry scans `Dockerfile`, `.claude/bkit-cloud.md` and `.github/workflows/*.yml` for a comment line directly above the pin: `# renovate: datasource=<datasource> depName=<name>` (optional `packageName=`, `versioning=`, `extractVersion=`). The next line is read as `[ARG|export] <NAME>_VERSION=<v>` or `<NAME>_VERSION: "<v>"`, `<NAME>_SPEC: "<pkg>==<v>"`, `npm install -g <pkg>@<v>`, or `bash "<installer>" <v>`. Renovate bumps the version only. A pin paired with a checksum (Vale, gh, jq, Node, actionlint) needs its sha256 updated by hand in the same PR, or the install fails closed.
|
|
415
428
|
|
|
429
|
+
**One source per tool.** A version that already lives in a file — an exact pin in a package manifest, or a build service's CLI pin such as `eas.json` `cli.version` — is read from that file by CI, never typed into the workflow: `npm i -g "turbo@$(node -p "require('./package.json').devDependencies.turbo")"`. A typed copy drifts, and Renovate bumps only one of the two. A tool with no such file gets one `<NAME>_VERSION` per workflow with the comment above, used by every call. A bare `npx <tool>` downloads the newest release on every run and skips the release-age wait, so pin it the same way.
|
|
430
|
+
|
|
416
431
|
**Land config on the default branch before the bot runs.** GitHub Apps and Dependabot read config from the default branch. The example sets `baseBranchPatterns: ["dev"]` (PRs land on `dev`) and `useBaseBranchConfig: "merge"` (edits on `dev` apply to dev-targeted runs). `useBaseBranchConfig` itself is read from the default branch, so it needs one merge there before dev-side edits take effect.
|
|
417
432
|
|
|
418
433
|
**Renovate, Mend.** Install the App at https://github.com/apps/renovate only after `renovate.json5` is on the default branch. No `gh api` equivalent. Within a few minutes the App opens an onboarding PR; merge it.
|
|
@@ -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
|
|
|
@@ -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
|
|
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
|
|
package/.bkit/shared/gitignore
CHANGED
|
@@ -47,8 +47,7 @@ docs/plans/*/logs/**/.lock
|
|
|
47
47
|
docs/plans/*/logs/**/.deferred-blocked
|
|
48
48
|
docs/plans/*/logs/**/.rebase-failed
|
|
49
49
|
|
|
50
|
-
#
|
|
51
|
-
.bkit/.dev.lock
|
|
50
|
+
# Cursor background-agent runtime marker
|
|
52
51
|
.bkit/.runtime-cursor
|
|
53
52
|
|
|
54
53
|
.bkit/.roadmap-shortlist.json
|
|
@@ -11,7 +11,7 @@ body:
|
|
|
11
11
|
Write this as the plan: a build with no plan builds from this issue.
|
|
12
12
|
- `/bkit-plan #<issue number>` turns it into a checked plan; the build then proves each **Test first** test fails before its code exists.
|
|
13
13
|
- `/bkit-build #<issue number>` builds straight from this issue and, when Tasks keep the exact shape below, proves each **Test first** test fails before its code exists. **Done when** guides rather than gates.
|
|
14
|
-
- `lite
|
|
14
|
+
- `build:lite` builds from this issue too but checks nothing: no failing-test proof, gates, PR or CI.
|
|
15
15
|
|
|
16
16
|
Keep the title short: it names the feature folder. Nothing ticks boxes in an issue.
|
|
17
17
|
- type: textarea
|
|
@@ -83,7 +83,7 @@ body:
|
|
|
83
83
|
description: |
|
|
84
84
|
The plan reads `**Parent design:**` and `**Audit reports:**` lines; the build refuses to start while an issue in the blocked-by block is open. Write them exactly as shown. Other references are not fetched, so use exact paths, ledger `key`s and issue numbers with titles.
|
|
85
85
|
placeholder: |
|
|
86
|
-
**Parent design:** [42-offline-sync-design.md](docs/plans/202610/42-offline-sync-design.md)
|
|
86
|
+
**Parent design:** [42-offline-sync-design.md](https://github.com/<owner>/<repo>/blob/dev/docs/plans/202610/42-offline-sync-design.md)
|
|
87
87
|
**Audit reports:** docs/audits/202610/security.md (findings security-3, security-5)
|
|
88
88
|
###### bkit:blocked-by start
|
|
89
89
|
- #<number>
|
|
@@ -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
|
|
@@ -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
|
-
#
|
|
87
|
-
-
|
|
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 [
|
|
97
|
-
|
|
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
|
|
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
|
-
#
|
|
366
|
-
-
|
|
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 [
|
|
376
|
-
|
|
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
|
|
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
|
|
@@ -827,7 +795,9 @@ jobs:
|
|
|
827
795
|
# bkit-tests-scope: runs-on: ubuntu-latest; timeout-minutes: 2; outputs: { plan: ${{ steps.scope.outputs.plan }} }
|
|
828
796
|
# steps:
|
|
829
797
|
# - name: Checkout Repository # [M] fetch-depth: 0 (turbo diffs need the base commit)
|
|
830
|
-
# - name: Install Turbo # [M]
|
|
798
|
+
# - name: Install Turbo # [M] bare global install, ~10-15s; no pnpm install. Version READ from
|
|
799
|
+
# # package.json, which pins turbo EXACTLY — never typed here, or this lane drifts from every
|
|
800
|
+
# # install-bearing lane: npm i -g "turbo@$(node -p "require('./package.json').devDependencies.turbo")"
|
|
831
801
|
# - name: Resolve Base Ref # [M] push base = the branch's last green run; shipped:
|
|
832
802
|
# # scripts/ci/lanes/resolve-push-base.mjs (falls back to github.event.before). deployments.md
|
|
833
803
|
# # § One run per branch or pull request.
|
|
@@ -1090,7 +1060,10 @@ jobs:
|
|
|
1090
1060
|
# block queues on {{DEFAULT_BRANCH}} too. Runs BEFORE the E2E / @live lanes: each of those needs: it and
|
|
1091
1061
|
# refuses unless production serves this run's build (by deployment id). Promotes the EXACT deployment_id
|
|
1092
1062
|
# bkit-tests-build-web published. Does not look the deployment up again by SHA. A 409 is success only when
|
|
1093
|
-
# the body says this id is already current production.
|
|
1063
|
+
# the body says this id is already current production. Before promoting it refuses, moving nothing, when
|
|
1064
|
+
# the id equals repo variable ROLLED_BACK_DEPLOYMENT_ID (set by the rollback) or when this commit is neither
|
|
1065
|
+
# production's commit nor a descendant of it (e.g. GitHub compare API status not ahead / identical), so a
|
|
1066
|
+
# re-run of an old run never moves production back. A red job means the release did not happen; the
|
|
1094
1067
|
# previous deployment stays live. On a default-branch push the capstone needs: it, so a skipped or failed
|
|
1095
1068
|
# deploy reds bkit-tests-check.
|
|
1096
1069
|
# The host must not auto-build the default branch, and any "hold promotion until a check passes"
|
|
@@ -7,10 +7,11 @@ name: bkit-cloud
|
|
|
7
7
|
# (via the opencode CLI `run` subcommand) — run the same `/bkit-auto <phase> <arg>`
|
|
8
8
|
# orchestrator against the committed `.claude/` / `.opencode/` config respectively.
|
|
9
9
|
#
|
|
10
|
-
# RUNTIME GATING —
|
|
11
|
-
# - ANTHROPIC_API_KEY set
|
|
10
|
+
# RUNTIME GATING — credential-presence auto-detect (in the context job):
|
|
11
|
+
# - ANTHROPIC_API_KEY secret set, OR both ANTHROPIC_FEDERATION_RULE_ID and
|
|
12
|
+
# ANTHROPIC_ORGANIZATION_ID repo variables set → claude job runs.
|
|
12
13
|
# - OPENCODE_PROVIDER_KEY set → opencode job runs.
|
|
13
|
-
# Both can run on one event (additive); a missing
|
|
14
|
+
# Both can run on one event (additive); a missing credential skips that job (zero
|
|
14
15
|
# billable runner minutes).
|
|
15
16
|
#
|
|
16
17
|
# Trigger surfaces:
|
|
@@ -21,8 +22,13 @@ name: bkit-cloud
|
|
|
21
22
|
# - workflow_dispatch: pick ANY phase (ship|debug|design|plan|build) for an issue.
|
|
22
23
|
# design/plan/build have no tracker-event trigger; they run only via dispatch.
|
|
23
24
|
#
|
|
24
|
-
# Required
|
|
25
|
-
#
|
|
25
|
+
# Required credentials (claude job): Claude GitHub App (one-time `/install-github-app`;
|
|
26
|
+
# claude-code-action@v1 authenticates as the App via `id-token: write` OIDC) + ONE of:
|
|
27
|
+
# - ANTHROPIC_API_KEY repo secret, or
|
|
28
|
+
# - workload identity federation (keyless): ANTHROPIC_FEDERATION_RULE_ID +
|
|
29
|
+
# ANTHROPIC_ORGANIZATION_ID repo variables (+ optional ANTHROPIC_SERVICE_ACCOUNT_ID /
|
|
30
|
+
# ANTHROPIC_WORKSPACE_ID) from a Claude Console federation rule. A set
|
|
31
|
+
# ANTHROPIC_API_KEY secret wins over federation — delete it when switching.
|
|
26
32
|
# Required secrets (opencode job): OPENCODE_PROVIDER_KEY (any provider key the
|
|
27
33
|
# committed .opencode/opencode.json references; fan-out maps it to known env var names).
|
|
28
34
|
# Required tracker label on the issue: `bkit:auto` (opt-in) for the CI-driven path.
|
|
@@ -115,20 +121,28 @@ jobs:
|
|
|
115
121
|
phase: ${{ steps.ctx.outputs.phase }}
|
|
116
122
|
arg: ${{ steps.ctx.outputs.arg }}
|
|
117
123
|
steps:
|
|
118
|
-
# A runner job whose
|
|
119
|
-
# below runs (no counter row, no checkout).
|
|
120
|
-
- name: Check runner
|
|
124
|
+
# A runner job whose credential is missing is a no-op; with neither job enabled,
|
|
125
|
+
# nothing below runs (no counter row, no checkout).
|
|
126
|
+
- name: Check runner credentials
|
|
121
127
|
id: gate
|
|
122
128
|
env:
|
|
123
129
|
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
130
|
+
ANTHROPIC_FEDERATION_RULE_ID: ${{ vars.ANTHROPIC_FEDERATION_RULE_ID }}
|
|
131
|
+
ANTHROPIC_ORGANIZATION_ID: ${{ vars.ANTHROPIC_ORGANIZATION_ID }}
|
|
124
132
|
OPENCODE_PROVIDER_KEY: ${{ secrets.OPENCODE_PROVIDER_KEY }}
|
|
125
133
|
run: |
|
|
126
134
|
claude=false
|
|
127
135
|
opencode=false
|
|
128
136
|
if [ -n "$ANTHROPIC_API_KEY" ]; then
|
|
129
137
|
claude=true
|
|
138
|
+
elif [ -n "$ANTHROPIC_FEDERATION_RULE_ID" ] && [ -n "$ANTHROPIC_ORGANIZATION_ID" ]; then
|
|
139
|
+
claude=true
|
|
140
|
+
elif [ -n "$ANTHROPIC_FEDERATION_RULE_ID" ]; then
|
|
141
|
+
echo "::notice::ANTHROPIC_ORGANIZATION_ID repo variable not set — federation needs it alongside ANTHROPIC_FEDERATION_RULE_ID; claude job no-op."
|
|
142
|
+
elif [ -n "$ANTHROPIC_ORGANIZATION_ID" ]; then
|
|
143
|
+
echo "::notice::ANTHROPIC_FEDERATION_RULE_ID repo variable not set — federation needs it alongside ANTHROPIC_ORGANIZATION_ID; claude job no-op."
|
|
130
144
|
else
|
|
131
|
-
echo "::notice::ANTHROPIC_API_KEY
|
|
145
|
+
echo "::notice::Neither the ANTHROPIC_API_KEY secret nor the ANTHROPIC_FEDERATION_RULE_ID + ANTHROPIC_ORGANIZATION_ID repo variables are set — claude job no-op."
|
|
132
146
|
fi
|
|
133
147
|
if [ -n "$OPENCODE_PROVIDER_KEY" ]; then
|
|
134
148
|
opencode=true
|
|
@@ -176,6 +190,13 @@ jobs:
|
|
|
176
190
|
HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
|
|
177
191
|
run: |
|
|
178
192
|
set -euo pipefail
|
|
193
|
+
# Cloud runs serve the GitHub tracker only: Linear cloud runs start from Cursor's
|
|
194
|
+
# Linear integration, and Jira runs locally only. Unset tracker → continue.
|
|
195
|
+
TRACKER=$(sed -n 's/.*"issueTracker"[[:space:]]*:[[:space:]]*"\([a-z]*\)".*/\1/p' package.json 2>/dev/null | head -1 || true)
|
|
196
|
+
if [ -n "$TRACKER" ] && [ "$TRACKER" != "github" ]; then
|
|
197
|
+
echo "::notice::bkit.issueTracker is '$TRACKER' — bkit-cloud.yml serves the GitHub tracker only; no-op exit."
|
|
198
|
+
echo "skip=true" >> "$GITHUB_OUTPUT"; exit 0
|
|
199
|
+
fi
|
|
179
200
|
if [ "$EVENT" = "workflow_dispatch" ]; then
|
|
180
201
|
# Dispatched: phase + issue come straight from inputs.
|
|
181
202
|
PHASE="$IN_PHASE"
|
|
@@ -440,8 +461,8 @@ jobs:
|
|
|
440
461
|
} >> "$GITHUB_OUTPUT"
|
|
441
462
|
|
|
442
463
|
# ---------------------------------------------------------------------------
|
|
443
|
-
# claude job — dispatch via claude-code-action@v1 (ANTHROPIC_API_KEY
|
|
444
|
-
# Runs only when the context job found
|
|
464
|
+
# claude job — dispatch via claude-code-action@v1 (ANTHROPIC_API_KEY or federation).
|
|
465
|
+
# Runs only when the context job found a claude credential and resolved a phase.
|
|
445
466
|
# OIDC auth via Claude GitHub App (id-token: write); requires one-time
|
|
446
467
|
# `/install-github-app` in the consumer repo.
|
|
447
468
|
# ---------------------------------------------------------------------------
|
|
@@ -456,7 +477,7 @@ jobs:
|
|
|
456
477
|
issues: write
|
|
457
478
|
actions: read
|
|
458
479
|
# id-token: write — required for claude-code-action@v1 to authenticate as the
|
|
459
|
-
# Claude GitHub App via OIDC (getOidcToken).
|
|
480
|
+
# Claude GitHub App via OIDC (getOidcToken), and for the federation token exchange.
|
|
460
481
|
id-token: write
|
|
461
482
|
steps:
|
|
462
483
|
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
@@ -501,6 +522,13 @@ jobs:
|
|
|
501
522
|
# orchestrator. GitHub MCP surface is always available; this workflow is
|
|
502
523
|
# GitHub-tracker only (cloud=claude requires tracker=github).
|
|
503
524
|
claude_args: "--allowed-tools=Bash,Edit,Write,Read,Grep,Glob,WebFetch,Skill,mcp__github__*"
|
|
525
|
+
# Workload identity federation: the action exchanges this job's GitHub OIDC token
|
|
526
|
+
# for a short-lived Claude API token. Unset variables pass empty; a set
|
|
527
|
+
# ANTHROPIC_API_KEY secret takes precedence.
|
|
528
|
+
anthropic_federation_rule_id: ${{ vars.ANTHROPIC_FEDERATION_RULE_ID }}
|
|
529
|
+
anthropic_organization_id: ${{ vars.ANTHROPIC_ORGANIZATION_ID }}
|
|
530
|
+
anthropic_service_account_id: ${{ vars.ANTHROPIC_SERVICE_ACCOUNT_ID }}
|
|
531
|
+
anthropic_workspace_id: ${{ vars.ANTHROPIC_WORKSPACE_ID }}
|
|
504
532
|
env:
|
|
505
533
|
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
|
506
534
|
GH_TOKEN: ${{ github.token }}
|
|
@@ -3,10 +3,10 @@
|
|
|
3
3
|
# bkit install does not write this file and does not overwrite a copy.
|
|
4
4
|
#
|
|
5
5
|
# FAST local gate only: format staged files (seconds). Heavier gates
|
|
6
|
-
# (typecheck/unit/format:check/prose)
|
|
7
|
-
# pre-push;
|
|
8
|
-
# by bkit-tests-check) — see bkit-ci.yml § FULL CI SCAFFOLD REFERENCE. Rule:
|
|
9
|
-
#
|
|
6
|
+
# (typecheck/unit/format:check/prose), the enforcing slop gate (slop:delta) and the
|
|
7
|
+
# integration tier are in pre-push; E2E/@live run ONLY in CI (bkit-tests / bkit-tests-live,
|
|
8
|
+
# enforced by bkit-tests-check) — see bkit-ci.yml § FULL CI SCAFFOLD REFERENCE. Rule: nothing
|
|
9
|
+
# here that pre-push runs again, and nothing that takes more than a few seconds. (lint:slop is `slop-scan scan` — report-only, never
|
|
10
10
|
# fails; the gate that fails on NEW findings is `slop:delta`, which runs in pre-push.)
|
|
11
11
|
#
|
|
12
12
|
# WHAT it runs lives in package.json `bkit:gate:format`, not here — the same script
|
|
@@ -14,3 +14,9 @@
|
|
|
14
14
|
# extras BELOW this line.
|
|
15
15
|
set -e
|
|
16
16
|
pnpm bkit:gate:format
|
|
17
|
+
|
|
18
|
+
# disk prune — keep this block last. Starts your min cleanup steps (`bkit disk prune`,
|
|
19
|
+
# .bkit/templates.md § Disk prune) in the background, at most once a day; with no step
|
|
20
|
+
# files it does nothing. Not a gate: a failure warns and the commit goes on.
|
|
21
|
+
pnpm -s bkit disk prune --mode=min --auto < /dev/null > /dev/null ||
|
|
22
|
+
echo "[pre-commit] WARN: disk prune failed; commit continues" >&2
|