@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.
Files changed (186) hide show
  1. package/.bkit/README.md +20 -7
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +14 -9
  4. package/.bkit/core/.bkit/README.md +19 -6
  5. package/.bkit/core/.bkit/cloud.md +77 -46
  6. package/.bkit/core/.bkit/comparison.md +3 -3
  7. package/.bkit/core/.bkit/install.md +21 -18
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +6 -3
  10. package/.bkit/core/.bkit/prompts.md +14 -10
  11. package/.bkit/core/.bkit/providers.md +7 -7
  12. package/.bkit/core/.bkit/templates.md +46 -10
  13. package/.bkit/core/.bkit/trackers.md +92 -38
  14. package/.bkit/core/.bkit/workflows.md +140 -116
  15. package/.bkit/core/AGENTS.md +2 -2
  16. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  17. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +2 -2
  23. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  25. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  26. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  28. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  30. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  31. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  33. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  35. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  36. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  38. package/.bkit/core/docs/templates/bkit-audit-issues.md +25 -8
  39. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  40. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  41. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  43. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  44. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  46. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  47. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  48. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  50. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  51. package/.bkit/core/engine/checks/after/auth.ts +88 -45
  52. package/.bkit/core/engine/checks/after/github.ts +18 -5
  53. package/.bkit/core/engine/checks/after/index.ts +1 -1
  54. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  55. package/.bkit/core/engine/checks/before/env.ts +28 -18
  56. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  57. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  58. package/.bkit/core/engine/checks/tips/catalogue.ts +31 -2
  59. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  60. package/.bkit/core/engine/cli.ts +27 -18
  61. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  62. package/.bkit/core/engine/commands/comply.ts +25 -16
  63. package/.bkit/core/engine/commands/install/install.ts +11 -4
  64. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  65. package/.bkit/core/engine/commands/land.ts +156 -0
  66. package/.bkit/core/engine/commands/lib.ts +10 -8
  67. package/.bkit/core/engine/commands/registry.ts +2 -0
  68. package/.bkit/core/engine/commands/tips.ts +7 -3
  69. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  70. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  71. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  72. package/.bkit/core/engine/commands/workflow/issues.ts +106 -42
  73. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  74. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  75. package/.bkit/core/engine/commands/workflow/prs.ts +14 -3
  76. package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
  77. package/.bkit/core/engine/commands/workflow/roadmap.ts +53 -54
  78. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  79. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  80. package/.bkit/core/engine/commands/workflow/steps.ts +26 -17
  81. package/.bkit/core/engine/commands/workflow/workflows.ts +442 -269
  82. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  83. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  84. package/.bkit/core/engine/install/manifest.ts +31 -10
  85. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  86. package/.bkit/core/engine/install/modules/core.ts +97 -4
  87. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  88. package/.bkit/core/engine/install/placeholders.ts +13 -17
  89. package/.bkit/core/engine/install/write.ts +37 -1
  90. package/.bkit/core/engine/render/trackers.ts +35 -23
  91. package/.bkit/core/engine/shared/egress.ts +6 -0
  92. package/.bkit/core/engine/shared/settings.ts +96 -1
  93. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  94. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  95. package/.bkit/core/prompts/bkit-audit-generate.md +80 -7
  96. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  97. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  98. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  99. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  100. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  101. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  102. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  103. package/.bkit/core/prompts/bkit-design-generate.md +2 -1
  104. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  105. package/.bkit/core/prompts/bkit-utility-update-decisions.md +4 -2
  106. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +4 -2
  107. package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
  108. package/.bkit/core/prompts/bkit-utility-update-failures.md +4 -2
  109. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +4 -2
  110. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +12 -5
  111. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  112. package/.bkit/core/workflows/bkit-auto.md +19 -6
  113. package/.bkit/core/workflows/bkit-build.md +64 -22
  114. package/.bkit/core/workflows/bkit-debug.md +72 -28
  115. package/.bkit/core/workflows/bkit-design.md +101 -37
  116. package/.bkit/core/workflows/bkit-plan.md +82 -31
  117. package/.bkit/core/workflows/bkit-ship.md +127 -108
  118. package/.bkit/shared/.bkit/.env.example +8 -0
  119. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  120. package/.bkit/shared/.claude/settings.json +4 -1
  121. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  122. package/.bkit/shared/.cursor/mcp.json +11 -4
  123. package/.bkit/shared/.mcp.json +11 -4
  124. package/.bkit/shared/.opencode/opencode.json +2 -0
  125. package/.bkit/shared/docs/deployments.md +44 -29
  126. package/.bkit/shared/docs/security.md +1 -1
  127. package/.bkit/shared/docs/testing.md +3 -3
  128. package/.bkit/shared/gitignore +1 -2
  129. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  130. package/.bkit/templates/.github/renovate.json5 +1 -1
  131. package/.bkit/templates/.github/workflows/bkit-ci.yml +29 -56
  132. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  133. package/.bkit/templates/.husky/pre-commit +10 -4
  134. package/.bkit/templates/.husky/pre-push +69 -12
  135. package/.bkit/templates/.lintstagedrc.json +5 -1
  136. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
  137. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
  138. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  139. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  140. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  141. package/CHANGELOG.md +85 -1
  142. package/README.md +102 -100
  143. package/dist/checks/after/auth.js +81 -45
  144. package/dist/checks/after/github.js +17 -5
  145. package/dist/checks/after/index.js +1 -1
  146. package/dist/checks/after/tools.js +1 -1
  147. package/dist/checks/before/env.js +24 -17
  148. package/dist/checks/before/mcp.js +4 -2
  149. package/dist/checks/status-holes.js +0 -1
  150. package/dist/checks/tips/catalogue.js +28 -2
  151. package/dist/checks/tips/index.js +44 -28
  152. package/dist/cli.js +27 -19
  153. package/dist/commands/ci/ci.js +100 -0
  154. package/dist/commands/comply.js +20 -13
  155. package/dist/commands/install/install.js +10 -4
  156. package/dist/commands/install/uninstall.js +42 -0
  157. package/dist/commands/land.js +129 -0
  158. package/dist/commands/lib.js +9 -6
  159. package/dist/commands/registry.js +2 -0
  160. package/dist/commands/tips.js +7 -3
  161. package/dist/commands/workflow/branches.js +300 -243
  162. package/dist/commands/workflow/disk.js +452 -0
  163. package/dist/commands/workflow/fids.js +22 -15
  164. package/dist/commands/workflow/issues.js +90 -41
  165. package/dist/commands/workflow/ledgers.js +26 -11
  166. package/dist/commands/workflow/locks.js +35 -130
  167. package/dist/commands/workflow/prs.js +8 -3
  168. package/dist/commands/workflow/repo.js +5 -0
  169. package/dist/commands/workflow/roadmap.js +52 -57
  170. package/dist/commands/workflow/runtime.js +3 -2
  171. package/dist/commands/workflow/status.js +32 -12
  172. package/dist/commands/workflow/steps.js +20 -13
  173. package/dist/commands/workflow/workflows.js +397 -251
  174. package/dist/commands/workflow/workstreams.js +3 -2
  175. package/dist/commands/workflow/worktrees.js +11 -1
  176. package/dist/install/manifest.js +30 -10
  177. package/dist/install/modules/cloud.js +3 -1
  178. package/dist/install/modules/core.js +95 -5
  179. package/dist/install/modules/opencode.js +6 -0
  180. package/dist/install/placeholders.js +13 -19
  181. package/dist/install/write.js +26 -2
  182. package/dist/render/trackers.js +34 -20
  183. package/dist/shared/egress.js +6 -0
  184. package/dist/shared/settings.js +44 -0
  185. package/dist/shared/timeouts.js +8 -7
  186. package/package.json +11 -2
@@ -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 commit on `main` (production) → unwind to prior known-good SHA. Steps 1-4 are host-agnostic; step 5 re-points the host (commands = Vercel example).
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
- - Known-good SHA on `main`. Confirm: `gh run list --branch main --status success --limit 5` (target SHA green).
25
- - Local repo on `main`, clean tree, `gh auth status` green.
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. **Save current protection JSON** for verbatim restore. GET and PUT shapes differ; raw GET avoids hand-mapping fields.
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
- gh api repos/{OWNER}/{REPO}/branches/main/protection > /tmp/main-protection.json
31
+ vercel ls --meta githubCommitSha=<green-sha>
32
+ vercel promote <prior-deployment-url>
33
33
  ```
34
- 2. **Disable protection** so force-reset is accepted.
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 api -X DELETE repos/{OWNER}/{REPO}/branches/main/protection
36
+ gh variable set ROLLED_BACK_DEPLOYMENT_ID --body <bad-deployment-id>
37
37
  ```
38
- 3. **Force-reset the `main` ref** to the known-good SHA.
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
- ### Why force-push on `main` alone is not enough
52
+ ### Revert, not reset
54
53
 
55
- - `git revert` on cross-branch squash (e.g. `feat/*` landed on `main` not `dev`) can delete files `main` code still references → tree fails CI despite "clean" history.
56
- - `feat/*`-onto-`main` is root cause of destructive recovery; production merges MUST come from `dev` (single-feature squash scope).
57
- - On `revert-*` branches pre-push drops only the **unit lane** (`bkit:gate:static` in place of `bkit:gate:static-unit`), so the static lane and the bkit drift gate still run → revert PR pushable when source state transitionally inconsistent.
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
- - `gh api repos/{OWNER}/{REPO}/git/refs/heads/main --jq .object.sha` must equal the green SHA.
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 the suite even when the SHA already has a green run. Use when investigating suspected ghost-greens. | Read by `Check SHA Cache` and `Detect Direct Push` |
121
- | `[force build]` | The lighter hammer. Exposes `should_force_build=true` + `run_level=full`; does **not** bypass `web_affected`, so no integration / e2e / @live unless web is genuinely affected. Rebuild without paying @live's side effects. Runs the suite even when the SHA already has a green run; deploy steps act on it only when they gate on the output. | Read by `Check SHA Cache` and `Detect Direct Push` |
120
+ | `[force cache]` | Busts the task-runner cache for the run — recompute instead of replaying cache hits (e.g. turbo: `TURBO_FORCE=1`). Runs a pull request's suite even when its files already passed a push run. Use when investigating suspected ghost-greens. | Read by `Check Tree Cache` and `Detect Direct Push` |
121
+ | `[force build]` | The lighter hammer. Exposes `should_force_build=true` + `run_level=full`; does **not** bypass `web_affected`, so no integration / e2e / @live unless web is genuinely affected. Rebuild without paying @live's side effects. Runs a pull request's suite even when its files already passed a push run; deploy steps act on it only when they gate on the output. | Read by `Check Tree Cache` and `Detect Direct Push` |
122
122
  | `[force full]` | The hammer. `run_level=full` **and** it bypasses `web_affected`, so integration, `bkit-tests-e2e-web`, and `bkit-tests-live-web` run on any commit, including docs-only. The E2E spec set does not change, because a PR already runs the full suite. `@live` stays **push-only** (a docs-only `[force full]` push reaches it through the effective `web_affected`; never a PR, never a dispatch). | Read by `Detect Direct Push` step |
123
123
  | `[verbose ci]` | Escalates log detail for one run. Shipped stub flips turbo / Node / Vercel / Supabase / Playwright knobs: `TURBO_LOG_LEVEL=full`, `NODE_OPTIONS=--trace-warnings --trace-deprecation` (a job-level `env:` key, never a `$GITHUB_ENV` write, which the runner rejects while still reporting success), `DEBUG=vercel:*,supabase:*`, plus Playwright `--trace=on` (when E2E stub enabled). Add your stack's equivalents to the same `env:`. Use when `bkit-debug` diagnose returns thin evidence; never for routine pushes (trace.zip files are MB-scale). See `testing.md` for the full knob list and the `--reporter=line` hostile gap. | Read by the job-level `env:` of `bkit-tests-static` (copy the same `env:` onto each lane) |
124
124
  | `[skip ci]` / `[skip actions]` | Honoured natively by GitHub Actions, so it suppresses workflow dispatch entirely. Use sparingly: the suppressed run will not appear in `gh run list`, and downstream `workflow_run` triggers will not fire. | Native GitHub behaviour, not a bkit-level toggle |
@@ -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. When the runtime can push `dev` (`RUNTIME_DEVPUSHES=true` — laptop, GitHub-Actions runner) it runs the local squash-merge and direct push: **no repo setting is required, and no PR is created**. When it cannot (cloud agent session, or an unclassified runtime) it 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.
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 SHA-cache short-circuit concludes `success` with step-level skips plus a `cache_skip` output, never `skipped`.
297
+ `bkit runs gate` covers the **common** violation shapes. A skipped non-capstone lane is **reported, not refused**, because the planned-vs-vacuous judgement belongs to the capstone, which takes every lane result as an input and already asserts it per lane. The gate cannot make that judgement itself: the jobs API reports no reason for a skip (a job skipped by a job-level `if:` never reaches a runner, so it carries an empty `steps` array), and a tree-cache short-circuit concludes `success` with step-level skips plus a `cache_skip` output, never `skipped`.
287
298
 
288
299
  **Code 16 is opt-in, and must stay that way.** It fires only for lanes named in `bkit.shipGateRequiredLanes` (package.json array); the default empty list never refuses. A blanket refuse-on-any-skip is **unsatisfiable by construction** for the CI shape bkit ships: a lane whose `if:` is event-scoped — `bkit-tests-live-web` runs on a push to `dev` or the default branch only — cannot run pre-merge at any head, so a pre-merge gate demanding it refuses every PR forever. Device lanes (`-ios` / `-android`) use the same rule on a pull request and a push; do not treat them as post-merge canaries. Name a lane in `shipGateRequiredLanes` only when your capstone does not assert it and the lane genuinely can run pre-merge. `BKIT_SHIP_GATE_OVERRIDE` remains the audited per-head escape hatch. What still carries the anti-vacuity guarantee is codes 10-15: a run exists, at this head, completed, not cancelled, capstone present, capstone green. Code 14 (green at a superseded head) requires `--branch`: the head-keyed run query is filtered server-side, so a moved head returns the same empty list as a head that never ran, and only a second branch-scoped query separates them. A run that is **present but degraded-but-not-skipped** (e.g. a required lane ran with a reduced test set due to a consumer config the gate cannot see) is a **residual risk named here, not claimed as covered**: the capstone is green because bkit's own `run_level` planner computed `full`; a consumer narrowing inside a lane bkit does not own is invisible to the gate. Keep the capstone (`bkit-tests-check`) as the sole branch-protection required check so `green == validated` survives a docs-only push; do not add per-lane required checks (a hollow lane then green-bars the capstone).
289
300
 
@@ -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`) → dev tree from Step 1 when `RUNTIME_DEVPUSHES=true` (modes 1-2), current working branch tree when `false` (mode 3 — cloud); see `.bkit/workflows.md` § Ship `BOOK_ROOT`. Post-merge tail = one `[skip ci]` close commit → push `dev` from the dev checkout (modes 1-2), or built off `origin/dev` → push `dev`, refused → `ship-close/{FID}` PR (mode 3).
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 + in-process integration). E2E, @live, service-backed integration excluded (CI — see below). never `--no-verify`.
17
+ > - Pre-push: `pnpm bkit:gate:static-unit-integration` when declared, else `pnpm bkit:gate:static-unit`, then `bkit check`; the `.husky/pre-push` template runs `bkit:gate:static` (no tests) on revert branches / commits. Gate scripts are consumer-owned; bkit's default = typecheck + lint + format:check + prose + slop:delta + `pnpm test` (unit tier only). Integration runs at pre-push once its gate is declared (local services such as a Docker database are fine). E2E, @live and tests against a deployed service excluded (CI — see below). never `--no-verify`.
18
18
 
19
19
  ## CI test tiers (the bkit scaffold)
20
20
 
@@ -393,8 +393,8 @@ Report coverage on each PR **without a paid product or a third-party service**
393
393
  - **Unit = the gate.** Put `coverage.thresholds.branches: <current>` in a `vitest.unit.config.ts` (`mergeConfig` over `vitest.config`) that **only** the unit run loads via `-c`, because **branches** is the meaningful floor (line / statement % overstates confidence); set it to your **current** coverage and ratchet up. vitest coverage is per-**run** (root config), **not** per-project, so `projects` does **not** scope it and a `thresholds` block in `vitest.config` would red **both** runs; the `-c` file is what keeps the gate off integration. A `--coverage.thresholds.branches=<n>` CLI flag also gates, but the report step cannot read it. 80% is convention, not best practice, because a fetishised high bar breeds assertion-free line-touching tests; the executed-≠-exercised rule (§ Validated means executed) matters far more than the number.
394
394
  - **Floor beside the figure.** The unit report step runs on **every** event (a red run too, via `!cancelled()` plus a `hashFiles` guard), passes `vite-config-path: vitest.unit.config.ts`, and comments only on same-repo PRs (`comment-on: pr`, else `none`), so every job summary, pushes included, shows the measured % against its 🎯 floor. The action regex-matches `<metric>: <number>` in that file's raw text: keep the floor on one unquoted line and no other metric name + colon + number in the file, because a broken match drops the target silently while the gate keeps passing.
395
395
  - **Integration = report-only.** Gate integration on **execution** (the capstone's `integration_ran > 0`), **not** a %. A whole-repo integration % is denominator-noise, because integration covers boundaries / flows, not pure logic, and rarely drives every branch, so a hard threshold on it punishes the correct pyramid shape. If you want a real integration %, add `--coverage.include='src/server/**'` on the integration run (same CLI-flag idiom as `--exclude`) to scope it to the integration surface, **then** set a floor, or **ratchet from current** — never a number picked from thin air.
396
- - **Share the unit gate with the build workflow.** Put the unit run (`vitest run -c vitest.unit.config.ts --coverage …`) in a `test:coverage:unit` script and chain it into `bkit:gate:static-unit` — the CI unit lane calls the script, `/bkit-build` Run Tests calls the gate, so the floor has **one source** and a regression fails in the worktree, not only on the PR. Never duplicate the command and sync it by comment, because that drifts. The build runs only the deepest declared `bkit:gate:*`, never the script by name: **left out of the chain, it never gates the build**. (bkit's own repo does exactly this.)
397
- - **Permissions.** The report steps need `pull-requests: write` — declare it at **job level** on the lane that posts. Job-level `permissions:` **replaces** the workflow-level block (not additive), and the SHA-cache step calls `gh run list`, so re-include `actions: read` too or it breaks. **Separate lanes:** with a lane per tier (recommended — see `deployments.md` § Parallel test lanes), each coverage comment posts from its own lane (unit-cov → `bkit-tests-unit`, integration-cov → `bkit-tests-integration`), so put the block on **each** lane that reports. With the combined starter, both live on `bkit-tests-unit`.
396
+ - **Share the unit gate with the build workflow.** Put the unit run (`vitest run -c vitest.unit.config.ts --coverage …`) in a `test:coverage:unit` script and chain it into `bkit:gate:static-unit` in place of `pnpm test`, never beside it (both run every unit test, so each runs twice) — the CI unit lane calls the script, `/bkit-build` Run Tests calls the gate, so the floor has **one source** and a regression fails in the worktree, not only on the PR. Never duplicate the command and sync it by comment, because that drifts. The build runs only the deepest declared `bkit:gate:*`, never the script by name: **left out of the chain, it never gates the build**. (bkit's own repo does exactly this.)
397
+ - **Permissions.** The report steps need `pull-requests: write` — declare it at **job level** on the lane that posts. Job-level `permissions:` **replaces** the workflow-level block (not additive), and the tree-cache step reads runs and jobs, so re-include `actions: read` too or it breaks. **Separate lanes:** with a lane per tier (recommended — see `deployments.md` § Parallel test lanes), each coverage comment posts from its own lane (unit-cov → `bkit-tests-unit`, integration-cov → `bkit-tests-integration`), so put the block on **each** lane that reports. With the combined starter, both live on `bkit-tests-unit`.
398
398
  - **Fork PRs.** `GITHUB_TOKEN` is read-only for PRs from a fork, so commenting fails — the shipped unit step sets `comment-on: none` there (its job summary still lands) and the integration step's `head.repo == repo` guard skips it; adopt the action's `workflow_run` two-workflow pattern if you must comment on fork PRs. The integration step is also guarded on `hashFiles(...)` so a repo with **no integration tier** skips it cleanly.
399
399
  - **Base-branch delta** (▲▼ vs the default branch) is **not** shipped by default, because it needs the base's `coverage-summary.json` (a second run or a stored artifact); wire the action's `json-summary-compare-path` if you want it.
400
400
 
@@ -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
- # Repo-global dev critical-section lock (cross-FID)
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:build` builds from this issue too but checks nothing: no failing-test proof, gates, PR or CI.
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.50" (pip spec in bkit-graphify.sh: value after `==`)
121
+ // GRAPHIFY_SPEC="graphifyy[sql]==0.9.70" (pip spec in bkit-graphify.sh: value after `==`)
122
122
  // npm install -g @opencode/cli@2.0.26 (npm global install)
123
123
  // bash "$RUNNER_TEMP/download-actionlint.bash" 1.7.12 (installer-script version argument)
124
124
  // Pins paired with a checksum (Vale, gh, jq, Node, actionlint) get the new VERSION
@@ -83,41 +83,25 @@ jobs:
83
83
  echo "🔊 [verbose ci] marker active — escalating log detail"
84
84
  echo "DEBUG=vercel:*,supabase:*" >> "$GITHUB_ENV"
85
85
 
86
- # [force build] / [force cache] run the suite even when this SHA already has a green run.
87
- - name: Check SHA Cache
86
+ # Pull requests only: the suite skips when this PR's files already passed a push run
87
+ # (scripts/ci/lanes/check-tree-cache.mjs). A push or dispatch run always runs it, and so
88
+ # does [force build] / [force cache] in the PR title.
89
+ - name: Check Tree Cache
88
90
  id: cache
89
91
  env:
90
92
  GH_TOKEN: ${{ github.token }}
93
+ REPO: ${{ github.repository }}
94
+ EVENT_NAME: ${{ github.event_name }}
95
+ JOB: ${{ github.job }}
91
96
  # User-controlled text (PR title) arrives via env: (runtime expansion,
92
97
  # injection-safe) — never inlined into the run: body.
93
98
  PR_TITLE: ${{ github.event.pull_request.title }}
94
- EVENT_NAME: ${{ github.event_name }}
95
99
  run: |
96
- if [ "$EVENT_NAME" = "pull_request" ]; then
97
- MSG="$PR_TITLE"
98
- else
99
- MSG=$(git log -1 --pretty=%B "$GITHUB_SHA" 2>/dev/null || echo "")
100
- fi
101
- case "$MSG" in
102
- *"[force build]"*|*"[force cache]"*)
103
- echo "skip=false" >> "$GITHUB_OUTPUT"
104
- echo "::notice::force marker present — ignoring SHA cache."
105
- exit 0 ;;
106
- esac
107
- SINCE=$(date -u -d '7 days ago' +%FT%TZ 2>/dev/null || date -u -v -7d +%FT%TZ)
108
- PRIOR=$(gh run list \
109
- --repo "$GITHUB_REPOSITORY" \
110
- --workflow "$GITHUB_WORKFLOW" \
111
- --status success \
112
- --limit 50 \
113
- --json headSha,createdAt \
114
- --jq "[.[] | select(.headSha == \"$GITHUB_SHA\") | select(.createdAt > \"$SINCE\")] | length" \
115
- 2>/dev/null || echo 0)
116
- if [ "${PRIOR:-0}" -gt 0 ]; then
117
- echo "skip=true" >> "$GITHUB_OUTPUT"
118
- echo "::notice::SHA $GITHUB_SHA has $PRIOR prior green run(s) since $SINCE — skipping suite."
100
+ if [ -f scripts/ci/lanes/check-tree-cache.mjs ]; then
101
+ node scripts/ci/lanes/check-tree-cache.mjs >> "$GITHUB_OUTPUT"
119
102
  else
120
103
  echo "skip=false" >> "$GITHUB_OUTPUT"
104
+ echo "::notice::scripts/ci/lanes/check-tree-cache.mjs not copied — running the suite."
121
105
  fi
122
106
 
123
107
  - name: Detect Direct Push
@@ -330,7 +314,7 @@ jobs:
330
314
  # and remote db push move out of this job when you adopt the scaffold below.
331
315
  bkit-tests-unit:
332
316
  runs-on: ubuntu-latest
333
- # bkit-tests-check reads both: cache_skip (a SHA-cache short-circuit asserts no count)
317
+ # bkit-tests-check reads both: cache_skip (a tree-cache short-circuit asserts no count)
334
318
  # and tests_ran (the executed-test count the Run Unit Tests step writes).
335
319
  outputs:
336
320
  cache_skip: ${{ steps.cache.outputs.skip }}
@@ -362,41 +346,25 @@ jobs:
362
346
  echo "🔊 [verbose ci] marker active — escalating log detail"
363
347
  echo "DEBUG=vercel:*,supabase:*" >> "$GITHUB_ENV"
364
348
 
365
- # [force build] / [force cache] run the suite even when this SHA already has a green run.
366
- - name: Check SHA Cache
349
+ # Pull requests only: the suite skips when this PR's files already passed a push run
350
+ # (scripts/ci/lanes/check-tree-cache.mjs). A push or dispatch run always runs it, and so
351
+ # does [force build] / [force cache] in the PR title.
352
+ - name: Check Tree Cache
367
353
  id: cache
368
354
  env:
369
355
  GH_TOKEN: ${{ github.token }}
356
+ REPO: ${{ github.repository }}
357
+ EVENT_NAME: ${{ github.event_name }}
358
+ JOB: ${{ github.job }}
370
359
  # User-controlled text (PR title) arrives via env: (runtime expansion,
371
360
  # injection-safe) — never inlined into the run: body.
372
361
  PR_TITLE: ${{ github.event.pull_request.title }}
373
- EVENT_NAME: ${{ github.event_name }}
374
362
  run: |
375
- if [ "$EVENT_NAME" = "pull_request" ]; then
376
- MSG="$PR_TITLE"
377
- else
378
- MSG=$(git log -1 --pretty=%B "$GITHUB_SHA" 2>/dev/null || echo "")
379
- fi
380
- case "$MSG" in
381
- *"[force build]"*|*"[force cache]"*)
382
- echo "skip=false" >> "$GITHUB_OUTPUT"
383
- echo "::notice::force marker present — ignoring SHA cache."
384
- exit 0 ;;
385
- esac
386
- SINCE=$(date -u -d '7 days ago' +%FT%TZ 2>/dev/null || date -u -v -7d +%FT%TZ)
387
- PRIOR=$(gh run list \
388
- --repo "$GITHUB_REPOSITORY" \
389
- --workflow "$GITHUB_WORKFLOW" \
390
- --status success \
391
- --limit 50 \
392
- --json headSha,createdAt \
393
- --jq "[.[] | select(.headSha == \"$GITHUB_SHA\") | select(.createdAt > \"$SINCE\")] | length" \
394
- 2>/dev/null || echo 0)
395
- if [ "${PRIOR:-0}" -gt 0 ]; then
396
- echo "skip=true" >> "$GITHUB_OUTPUT"
397
- echo "::notice::SHA $GITHUB_SHA has $PRIOR prior green run(s) since $SINCE — skipping suite."
363
+ if [ -f scripts/ci/lanes/check-tree-cache.mjs ]; then
364
+ node scripts/ci/lanes/check-tree-cache.mjs >> "$GITHUB_OUTPUT"
398
365
  else
399
366
  echo "skip=false" >> "$GITHUB_OUTPUT"
367
+ echo "::notice::scripts/ci/lanes/check-tree-cache.mjs not copied — running the suite."
400
368
  fi
401
369
 
402
370
  - name: Detect Direct Push
@@ -543,7 +511,7 @@ jobs:
543
511
  # (a CLI flag on the integration run, same idiom as --exclude above) to scope it to the integration
544
512
  # surface THEN set a floor, or ratchet from current — never a picked number. See docs/testing.md § Coverage on PRs.
545
513
  # 4. JOB-LEVEL permissions on bkit-tests-unit. Job-level REPLACES the workflow-level block (not additive), and the
546
- # Check SHA Cache step calls `gh run list`, so you MUST re-include actions: read or the cache step breaks:
514
+ # Check Tree Cache step reads runs and jobs, so you MUST re-include actions: read or the cache step breaks:
547
515
  # permissions:
548
516
  # actions: read
549
517
  # contents: read
@@ -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] npm i -g turbo@<ver> (bare, ~10-15s; no pnpm install)
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. A red job means the release did not happen; the
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 — secret-presence auto-detect (in the context job):
11
- # - ANTHROPIC_API_KEY set → claude job runs.
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 secret skips that job (zero
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 secrets (claude job): ANTHROPIC_API_KEY + Claude GitHub App (one-time
25
- # `/install-github-app` — grants `id-token: write` OIDC for claude-code-action@v1).
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 secret is missing is a no-op; with neither secret set, nothing
119
- # below runs (no counter row, no checkout).
120
- - name: Check runner secrets
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 not set — claude job no-op."
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 required).
444
- # Runs only when the context job found ANTHROPIC_API_KEY set and resolved a phase.
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) and the enforcing slop gate (slop:delta) are in
7
- # pre-push; integration/E2E/@live run ONLY in CI (bkit-tests / bkit-tests-live, enforced
8
- # by bkit-tests-check) — see bkit-ci.yml § FULL CI SCAFFOLD REFERENCE. Rule: anything needing
9
- # a deployed URL, a DB, or >a few seconds belongs in a CI tier, not a hook. (lint:slop is `slop-scan scan` — report-only, never
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