@cbartens/bkit 5.0.0 → 5.0.2

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 (72) hide show
  1. package/.bkit/README.md +12 -16
  2. package/.bkit/core/.agents/rules.md +57 -57
  3. package/.bkit/core/.bkit/README.md +11 -15
  4. package/.bkit/core/.bkit/cloud.md +22 -30
  5. package/.bkit/core/.bkit/comparison.md +36 -28
  6. package/.bkit/core/.bkit/install.md +55 -150
  7. package/.bkit/core/.bkit/jsonl.md +5 -5
  8. package/.bkit/core/.bkit/providers.md +6 -3
  9. package/.bkit/core/.bkit/templates.md +9 -7
  10. package/.bkit/core/.bkit/trackers.md +1 -1
  11. package/.bkit/core/.bkit/workflows.md +7 -3
  12. package/.bkit/core/engine/checks/after/auth.ts +16 -114
  13. package/.bkit/core/engine/checks/after/ci-yml.ts +36 -74
  14. package/.bkit/core/engine/checks/after/github.ts +1 -1
  15. package/.bkit/core/engine/checks/after/index.ts +158 -184
  16. package/.bkit/core/engine/checks/after/suppression.ts +53 -0
  17. package/.bkit/core/engine/checks/before/env.ts +5 -19
  18. package/.bkit/core/engine/checks/before/files.ts +2 -0
  19. package/.bkit/core/engine/cli.ts +4 -8
  20. package/.bkit/core/engine/commands/install/doctor.ts +9 -2
  21. package/.bkit/core/engine/commands/install/install.ts +24 -2
  22. package/.bkit/core/engine/commands/install/uninstall.ts +56 -1
  23. package/.bkit/core/engine/commands/install/upgrade.ts +14 -3
  24. package/.bkit/core/engine/commands/lib.ts +4 -3
  25. package/.bkit/core/engine/install/cloud-env.ts +4 -2
  26. package/.bkit/core/engine/install/modules/cloud.ts +3 -4
  27. package/.bkit/core/engine/install/modules/core.ts +33 -13
  28. package/.bkit/core/engine/install/modules/opencode.ts +34 -13
  29. package/.bkit/core/engine/install/payload-links.ts +150 -0
  30. package/.bkit/core/engine/install/template-copies.ts +1 -1
  31. package/.bkit/core/engine/shared/egress.ts +1 -1
  32. package/.bkit/core/workflows/bkit-debug.md +19 -12
  33. package/.bkit/shared/.bkit/.env.example +43 -36
  34. package/.bkit/shared/.claude/bkit-cloud.md +1 -1
  35. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  36. package/.bkit/shared/.opencode/opencode.json +3 -1
  37. package/.bkit/shared/docs/deployments.md +7 -10
  38. package/.bkit/shared/docs/security.md +1 -1
  39. package/.bkit/shared/gitignore +5 -0
  40. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +0 -5
  41. package/.bkit/templates/.cursor/Dockerfile +1 -1
  42. package/.bkit/templates/.cursor/environment.json +1 -1
  43. package/.bkit/templates/.github/renovate.json5 +0 -15
  44. package/.bkit/templates/.github/workflows/bkit-ci.yml +7 -24
  45. package/.bkit/templates/.github/workflows/bkit-cloud.yml +0 -2
  46. package/.bkit/templates/.github/workflows/bkit-renovate.yml +7 -10
  47. package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +125 -12
  48. package/CHANGELOG.md +37 -0
  49. package/README.md +96 -38
  50. package/dist/checks/after/auth.js +16 -108
  51. package/dist/checks/after/ci-yml.js +30 -67
  52. package/dist/checks/after/github.js +1 -1
  53. package/dist/checks/after/index.js +138 -154
  54. package/dist/checks/after/suppression.js +39 -0
  55. package/dist/checks/before/env.js +5 -15
  56. package/dist/checks/before/files.js +2 -0
  57. package/dist/cli.js +4 -8
  58. package/dist/commands/install/doctor.js +4 -2
  59. package/dist/commands/install/install.js +16 -2
  60. package/dist/commands/install/uninstall.js +45 -1
  61. package/dist/commands/install/upgrade.js +14 -3
  62. package/dist/commands/lib.js +4 -3
  63. package/dist/install/cloud-env.js +4 -2
  64. package/dist/install/modules/cloud.js +3 -4
  65. package/dist/install/modules/core.js +33 -13
  66. package/dist/install/modules/opencode.js +34 -14
  67. package/dist/install/payload-links.js +119 -0
  68. package/dist/install/template-copies.js +1 -1
  69. package/dist/shared/egress.js +1 -1
  70. package/package.json +25 -3
  71. package/.bkit/core/engine/checks/after/vercel.ts +0 -101
  72. package/dist/checks/after/vercel.js +0 -102
@@ -546,22 +546,29 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
546
546
  "{BKIT}" branches push --mode=feature --require-ci >/dev/null
547
547
  ```
548
548
  Hold the close's `parentSha` as `{CLOSE_PARENT}`.
549
- 3. **Run only if** `PUSH_MODE` = LOCAL — record the close row and audit the landed commit; `{LIVE_SKIPPED}` = `--field="testsLiveSkipped=No live tests ran, runtime-only defects not gated (not declared or opted out)."` when `TEST_SCOPE` lacks `live`, else empty:
549
+ 3. Probe live PR state (`{PR_OPEN}` = 0 with no probe when `BRANCH` = `dev` **or** `main`):
550
550
  ```bash
551
- "{BKIT}" steps done --file="{STATUS}" --workflow=debug --step=debug-close-workflow --parent-sha={CLOSE_PARENT} {LIVE_SKIPPED} --commit=none >/dev/null || exit 1
552
- "{BKIT}" prs transport-row --file="{STATUS}" --kind=close --shape=push --sha={CLOSE_PARENT} --scan --cross-check=gh
551
+ "{BKIT}" prs probe --head="{BRANCH}" --base=dev
553
552
  ```
553
+ - **If** exit 0 → `{PR_OPEN}` = 1; hold `number` as `{PR_NUMBER}`, `url` as `{PR_URL}`.
554
+ - **If** exit 1 → `{PR_OPEN}` = 0.
555
+ - **If** exit 80 → `list_pull_requests` (head `{BRANCH}`, base `dev`, state open) → found → `{PR_OPEN}` = 1 with its `number` / `url`; none → `{PR_OPEN}` = 0; record via `"{BKIT}" prs transport-row --file="{STATUS}" --kind=fallback --asserted-by=<re-read>`.
556
+ - **Else** → **Failure Path**.
557
+ - **If** `{PR_OPEN}` = 0 → record the close row and audit the landed commit; `{LIVE_SKIPPED}` = `--field="testsLiveSkipped=No live tests ran, runtime-only defects not gated (not declared or opted out)."` when `TEST_SCOPE` lacks `live`, else empty:
558
+ ```bash
559
+ "{BKIT}" steps done --file="{STATUS}" --workflow=debug --step=debug-close-workflow --parent-sha={CLOSE_PARENT} {LIVE_SKIPPED} --commit=none >/dev/null || exit 1
560
+ "{BKIT}" prs transport-row --file="{STATUS}" --kind=close --shape=push --sha={CLOSE_PARENT} --scan --cross-check=gh
561
+ ```
554
562
  4. Set `TRIGGER_PR`:
555
563
  - **If** `BRANCH` = `dev` **or** `main` → push to trigger branch (CI fires) → `TRIGGER_PR` = 0.
556
- - **If** `PUSH_MODE` = PR → push fires `pull_request` event → `TRIGGER_PR` = 0.
557
- - **If** `PUSH_MODE` = LOCAL → `TRIGGER_PR` = 1.
558
- - **Else** → **Failure Path**.
559
- 5. **If** `TRIGGER_PR` = 1 → create PR (body names `docs/plans/{YYYYMM}/{FID}-plan.md` if present):
564
+ - **If** `{PR_OPEN}` = 1 → the close push fires `pull_request` → `TRIGGER_PR` = 0.
565
+ - **Else** → `TRIGGER_PR` = 1.
566
+ 5. **If** `TRIGGER_PR` = 1 → create or adopt the PR (body names `docs/plans/{YYYYMM}/{FID}-plan.md` if present); `--existing=reuse` adopts a PR that appeared since sub-step 3:
560
567
  ```bash
561
- "{BKIT}" prs open --fid={FID} --title="feat({FID}): debug-remediated" --issue="{ISSUE_ID}" --plan=docs/plans/{YYYYMM}/{FID}-plan.md
568
+ "{BKIT}" prs open --fid={FID} --title="feat({FID}): debug-remediated" --issue="{ISSUE_ID}" --existing=reuse --plan=docs/plans/{YYYYMM}/{FID}-plan.md
562
569
  ```
563
570
  Route:
564
- - **If** exit 0 → hold `number` as `{PR_NUMBER}`, `url` as `{PR_URL}`.
571
+ - **If** exit 0 → hold `number` as `{PR_NUMBER}`, `url` as `{PR_URL}` (created, or the adopted PR).
565
572
  - **If** exit 80 → `create_pull_request` with the printed `title` / `body` / `base` / `head` → its number as `{PR_NUMBER}`, URL as `{PR_URL}`.
566
573
  - **Else** → **Failure Path**.
567
574
  6. **If** `TRIGGER_PR` = 1 → commit and push the CI-triggering head (`{LABEL_FLAGS}` = one `--label=<name>` per re-read `LABELS` entry):
@@ -570,7 +577,7 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
570
577
  git add -A && git commit --allow-empty -m "chore({FID}): create-pr bkit [verbose ci]${AUTO_ROUTE_SUFFIX}" || exit 1
571
578
  "{BKIT}" branches push --mode=feature --require-ci
572
579
  ```
573
- 7. **Run only if** `PUSH_MODE` = PR **or** `TRIGGER_PR` = 1 — CI-Dispatch Gate on the pushed head; it records `{DISPATCH_ROW}`, cross-checks the transport and records the close transport. `{DISPATCH_ROW}` = `--step=debug-close-workflow {LIVE_SKIPPED}` in `PUSH_MODE` = PR, `--step=debug-create-pr --artifact={PR_URL}` after a created PR; `{LABEL_FLAGS}` as in sub-step 6:
580
+ 7. **Run only if** `{PR_OPEN}` = 1 **or** `TRIGGER_PR` = 1 — CI-Dispatch Gate on the pushed head; it records `{DISPATCH_ROW}`, cross-checks the transport and records the close transport. `{DISPATCH_ROW}` = `--step=debug-close-workflow {LIVE_SKIPPED}` when `{PR_OPEN}` = 1, `--step=debug-create-pr --artifact={PR_URL}` after a created PR; `{LABEL_FLAGS}` as in sub-step 6:
574
581
  ```bash
575
582
  "{BKIT}" runs dispatch --pr={PR_NUMBER} --fid={FID} {LABEL_FLAGS} --file="{STATUS}" --workflow=debug {DISPATCH_ROW} {CI_REENTRY}
576
583
  ```
@@ -617,7 +624,7 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
617
624
  "{BKIT}" steps gate --file="{STATUS}" --workflow=debug --step=debug-close-workflow
618
625
  ```
619
626
 
620
- - [ ] Mechanical checks passed (`steps gate` exit 0: `debug-close-workflow` row, with `testsLiveSkipped` if no live test, `ciDispatch` if PR-mode)
627
+ - [ ] Mechanical checks passed (`steps gate` exit 0: `debug-close-workflow` row, with `testsLiveSkipped` if no live test, `ciDispatch` on every feature-branch close)
621
628
  - [ ] PR title `[verbose ci]` stripped (if `PUSH_MODE` = PR)
622
629
 
623
630
  <!-- bkit:tracker true start -->
@@ -628,7 +635,7 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
628
635
 
629
636
  - [ ] No-leak Assertion passed (no `[DEBUG-OBSERVE]` lines survive)
630
637
  - [ ] Close committed and pushed (`workflows close` committed telemetry on `feat/{FID}`; `branches push --require-ci` exit 0)
631
- - [ ] Trigger-PR determined (`TRIGGER_PR`); if PR created: `PR_URL`, `PR_NUMBER` held, step `debug-create-pr` recorded with the PR URL and `ciDispatch`, changes pushed
638
+ - [ ] `TRIGGER_PR` set from the live `prs probe` (`{PR_OPEN}`), not Step-1 `PUSH_MODE`; if a PR was created or adopted: `PR_URL`, `PR_NUMBER` held, step `debug-create-pr` recorded with the PR URL and `ciDispatch`, changes pushed
632
639
  - [ ] CI-Dispatch gate ran (`runs dispatch` exit 0, close transport recorded)
633
640
  - [ ] Final return displayed (`debug-summary.md` content verbatim)
634
641
 
@@ -7,55 +7,62 @@
7
7
  #
8
8
  # Cloud sessions (Claude on the web, Cursor Background Agents) set the SAME
9
9
  # variable names in their respective dashboards — never in this file.
10
-
11
- # BKIT_NPM_TOKEN — npm granular access token with read + write access to the
12
- # @cbartens scope. The Release workflow publishes @cbartens/bkit to npmjs.org
13
- # with it (same name as the repo secret, Actions → Secrets), and local
14
- # maintenance uses it too (`npm whoami`, manual publishes). npm is restricting
15
- # tokens that bypass 2FA (account changes Aug 2026, direct publishing Jan 2027)
16
- # — create a granular token and keep 2FA enrolled.
17
- # Generate at: https://www.npmjs.com/settings/cbartens/tokens
18
- BKIT_NPM_TOKEN=
19
-
20
- # BKIT_GH_TOKEN_INSTALL — GitHub classic PAT with `read:packages` scope. Used by pnpm
21
- # to authenticate to the GitHub Packages npm registry (npm.pkg.github.com) for
22
- # @cbartens/* packages. Fine-grained PATs are rejected by GitHub Packages
23
- # (HTTP 403) — must be classic.
24
- # Generate at: https://github.com/settings/tokens (Tokens (classic) → Generate)
25
- # The project .npmrc carries ONLY the @cbartens registry mapping; the auth token
26
- # is written into pnpm's user-level config via `pnpm config set` (CI step, local
27
- # once, Vercel installCommand) — version-proof across pnpm 10.x/11.x. pnpm >=10.34.3
28
- # 401s on a project-.npmrc ${BKIT_GH_TOKEN_INSTALL} env-substitution. See KN-CORE-7.
29
- BKIT_GH_TOKEN_INSTALL=
10
+ #
11
+ # Keep ~/.config/bkit/launchd.env in sync. GUI/daemon apps (the opencode desktop
12
+ # app, Cursor launched from the Dock, and opencode's background service) do not
13
+ # inherit direnv's exports — they read what `ai.bkit.launchd` publishes to launchd
14
+ # from that file (see .bkit/providers.md § macOS GUI-isolation). It DUPLICATES
15
+ # these tokens and does not track this file, so after ROTATING a value here you
16
+ # must re-sync launchd.env or the app keeps the stale one — e.g. a revoked
17
+ # BKIT_GH_TOKEN makes the GitHub MCP 401 and opencode offers an OAuth "sign in"
18
+ # that then fails with "dynamic auth not supported". Then restart long-lived
19
+ # consumers: opencode snapshots its env at launch, so `opencode service restart`.
30
20
 
31
21
  # Optional examples — not required bkit tooling. Listed so direnv has a name to
32
22
  # load if you use that surface; leave blank otherwise.
33
23
 
34
- # BKIT_GH_TOKEN — the general-purpose bkit GitHub token (fine-grained PAT). One token
35
- # for every GitHub *API* operation bkit tooling performs:
24
+ # BKIT_GH_TOKEN — the general-purpose bkit GitHub token. One token for every GitHub
25
+ # *API* operation bkit tooling performs:
36
26
  # - the GitHub MCP server (api.githubcopilot.com/mcp/) via the Authorization header
37
- # in .mcp.json / .cursor/mcp.json;
27
+ # in .mcp.json / .cursor/mcp.json / .opencode/opencode.json;
38
28
  # - self-hosted Renovate's PLATFORM auth (repo Actions secret) when you copy
39
29
  # the example `.github/workflows/bkit-renovate.yml` — opens PRs,
40
30
  # pushes renovate/* branches, edits workflow SHAs, maintains the dashboard issue.
41
- # Required Repository permissions (as labelled in the fine-grained-PAT UI; scope to the
31
+ #
32
+ # Token TYPE — choose by how many repos / owners bkit touches:
33
+ # - ONE repo, or every repo under ONE owner (a single user, or a single org) →
34
+ # FINE-GRAINED PAT (resource owner = that user or org). Preferred — repo-scoped
35
+ # blast radius + mandatory expiry. Permissions below.
36
+ # - MORE THAN ONE repo across DIFFERENT owners (two or more orgs, or a user + an org) →
37
+ # CLASSIC PAT. A fine-grained PAT is limited to a SINGLE resource owner and cannot
38
+ # span organizations, so it cannot cover this case. Classic reaches every repo your
39
+ # user can access — keep the expiry short; an org may block classic PATs (403), and
40
+ # SAML SSO orgs need the token authorized per org (authorization expires; re-authorize).
41
+ #
42
+ # FINE-GRAINED PAT — Repository permissions (as labelled in the token UI; scope to the
42
43
  # repos you work on): Contents: Read and write · Pull requests: Read and write · Issues:
43
44
  # Read and write · Workflows: Read and write · Commit statuses: Read and write (Renovate
44
45
  # reads a commit's CI state to open the PR + posts its own stability checks; without it it
45
46
  # creates the renovate/* branch but 403s on /commits/{sha}/statuses and never opens the PR)
46
47
  # · Dependabot alerts: Read (GitHub's vulnerability feed, for security-fix PRs) · Metadata:
47
- # Read-only. (Actions: Read for the MCP server's run-status queries.) There is NO "Checks"
48
- # permission on fine-grained PATs — check-run writes are App-only, so a PAT-based Renovate
49
- # uses commit statuses instead.
50
- # Self-hosted Renovate commit authorship: on a PERSONAL-account token also add the Account
51
- # permission "Email addresses: Read" so commits use your verified email. ORG-owned tokens
52
- # have NO Email-addresses permission — instead set the repo variable RENOVATE_GIT_AUTHOR
53
- # (Settings -> Secrets and variables -> Actions -> Variables), e.g. `Renovate Bot <renovate@your-domain>`.
54
- # This is a WRITE token — keep it SEPARATE from BKIT_GH_TOKEN_INSTALL, and do NOT put it
55
- # on read-only surfaces (Vercel env / project .npmrc). It also CANNOT authenticate to
56
- # GitHub Packages (fine-grained PATs get 403 there) — registry/lockfile auth stays on
57
- # the classic BKIT_GH_TOKEN_INSTALL above (that is why Renovate's hostRules use _INSTALL).
58
- # Generate at: https://github.com/settings/personal-access-tokens
48
+ # Read-only. (Actions: Read for the MCP server's run-status queries.) Add Organization
49
+ # Projects: Read and write only for board sync (org-owned boards; shown under the token's
50
+ # Organizations tab, not Repository permissions). There is NO "Checks" permission on
51
+ # fine-grained PATs — check-run writes are App-only, so a PAT-based Renovate uses commit
52
+ # statuses instead.
53
+ # CLASSIC PAT — scopes: `repo` (issues / PRs / contents / commit statuses) · `workflow`
54
+ # · `read:org` · `project` (board sync) · `security_events` (Dependabot / code-scanning
55
+ # feed) · optional `user:email` (Renovate commit authorship on a personal account). There
56
+ # is no separate Checks scope on classic either — commit statuses come via `repo`.
57
+ # Self-hosted Renovate commit authorship: on a PERSONAL-account fine-grained token also add
58
+ # the Account permission "Email addresses: Read" so commits use your verified email.
59
+ # ORG-owned tokens have NO Email-addresses permission — instead set the repo variable
60
+ # RENOVATE_GIT_AUTHOR (Settings -> Secrets and variables -> Actions -> Variables), e.g.
61
+ # `Renovate Bot <renovate@your-domain>` (classic equivalent: the `user:email` scope).
62
+ # This is a WRITE token — do NOT put it on read-only surfaces (Vercel env / project
63
+ # .npmrc).
64
+ # Generate at: https://github.com/settings/personal-access-tokens (fine-grained)
65
+ # https://github.com/settings/tokens (classic)
59
66
  BKIT_GH_TOKEN=
60
67
 
61
68
  # BKIT_LINEAR_API_KEY — Linear personal API key. Used by the Linear MCP server
@@ -112,6 +112,6 @@ Your `/bkit-*` skills and bkit subagents load automatically from the committed
112
112
 
113
113
  ---
114
114
 
115
- `BKIT_GH_TOKEN` fine-grained PAT permissions, the `gh auth login --with-token`
115
+ `BKIT_GH_TOKEN` PAT permissions (fine-grained vs classic), the `gh auth login --with-token`
116
116
  step, MCP OAuth flow, and the one-environment-per-repo rationale all live in
117
117
  `.bkit/cloud.md` § Claude Code on the web.
@@ -43,8 +43,8 @@ Add **each** line below as a secret (Name = the key, Value = the value). Set the
43
43
 
44
44
  - `LINEAR_ISSUE_ID` (Linear tracker) / `GITHUB_ISSUE_ID` (GitHub tracker) are injected
45
45
  **per session** by the Cursor integration — do **not** add them here.
46
- - `BKIT_GH_TOKEN` fine-grained PAT permissions are documented in `.bkit/cloud.md`
47
- § BKIT_GH_TOKEN permissions (identical scope to the Claude side).
46
+ - `BKIT_GH_TOKEN` PAT permissions (fine-grained for one owner, classic across owners) are documented in `.bkit/cloud.md`
47
+ § `BKIT_GH_TOKEN` — token permissions (identical scope to the Claude side).
48
48
  - Secrets are encrypted at rest and in transit and scoped to the environment.
49
49
 
50
50
  ## 3 · Toolchain (in-repo — nothing to paste)
@@ -15,7 +15,9 @@
15
15
  "glob": "allow",
16
16
  "task": "allow",
17
17
  "websearch": "allow",
18
- "webfetch": "ask",
18
+ "webfetch": {
19
+ "*": "ask"
20
+ },
19
21
  "bash": {
20
22
  "*": "allow",
21
23
  "sudo *": "ask",
@@ -212,11 +212,13 @@ Ships in the `bkit-ci.yml` template as the `Check Default Branch Lags Dev` step;
212
212
 
213
213
  ### One CI run per dev commit (release PR mirrors the `dev` push run)
214
214
 
215
- Optional. A same-repo `dev` → `main` PR's head is the `dev` tip the `dev` push run already tests, because a full PR run repeats the slowest run in the repo. Mirror mode runs it once.
215
+ Optional. A same-repo promotion PR into the default branch — head `dev`, or a `release/*` branch cut at the `dev` tip — has the same head the `dev` push run already tests, so a full PR run repeats the slowest run in the repo. Mirror mode runs it once.
216
216
 
217
- - **Planner** (`Decide Release Mirror`, `bkit-tests-scope`): `pull_request` + head repo == this repo + `head_ref == dev` + base == default branch → `mirror_push_run=true`, `run_level=none`, `run_e2e` / `run_live` / `run_migration` / `web_affected=false`. Every lane skips. Field is required in the plan (`false` otherwise). Fork PRs and every other head / base pair keep the normal plan.
217
+ - **Planner** (`Decide Release Mirror`, `bkit-tests-scope`): `pull_request` + head repo == this repo + base == default branch + `head_ref` is a promotion branch (`dev`, or `release/*`) → `mirror_push_run=true`, `run_level=none`, `run_e2e` / `run_live` / `run_migration` / `web_affected=false`. Every lane skips. Field is required in the plan (`false` otherwise). Fork PRs and every other head / base pair keep the normal plan.
218
218
  - **Capstone** (`Mirror Push Run`, `bkit-tests-check`, before `Assert Test Plan Followed`): `bkit runs mirror --head <PR head sha> --branch dev --max-minutes 170`. Waits for the `dev` push run at that SHA (each poll is `bkit runs gate --event push`) and passes only when its capstone passed. The step runs bkit, so the job needs a checkout and installed dependencies, both ungated. Neither step `continue-on-error`.
219
219
  - **Never skip the PR's required check instead.** A skipped required check can read as passed on the PR while the push run is red.
220
+ - **`release/*` resolves the push run by SHA.** A `release/*` head with no green `dev` push run (extra commits past the `dev` tip) fails the mirror red (exit `3`) — safe, not silent.
221
+ - **bkit's own CI adopts this.** `Decide Release Mirror` accepts `dev` and `release/*`; `Decide Run Level` has no merged-PR → `light` arm, so every `dev` push resolves `full` (precondition 1); the capstone's `Mirror Push Run` runs `bkit runs mirror --head="$PR_HEAD_SHA" --branch=dev --max-minutes=170`.
220
222
 
221
223
  <!-- prettier-ignore -->
222
224
  | Push run at PR head | PR `bkit-tests-check` | `bkit runs mirror` exit |
@@ -267,7 +269,7 @@ Undocumented, and invisible to the toolchain, because the file stays valid YAML,
267
269
 
268
270
  **Docs-only-diff precondition:** the `dev`-trigger path routes every post-merge CI failure to `/bkit-debug`. This is only correct for docs-only diffs if the consumer's `bkit-ci.yml` deploy-await step treats a host-cancelled build as skip, not red (skip e2e, stay green; e.g. Vercel `CANCELED`), but if a consumer reds on a host-cancelled build, every docs-only squash-merge to `dev` false-dispatches `/bkit-debug` and burns loop-cap budget. Verify this per consumer before relying on the `dev` trigger.
269
271
 
270
- **Consumer-repo acceptance note:** the full happy-path loop (squash-merge → post-merge CI → `workflow_run` → `/bkit-debug` dispatch → fix PR → re-merge) is only exercisable on consumer repos with `bkit-cloud.yml` installed and its dispatch secrets wired (see `BKIT_GH_TOKEN_INSTALL` — presence matrix, below, and the cloud-agent auth surfaces in `docs/security.md`). A consumer without `bkit-cloud.yml` installed, or without CI running on `push: branches: [dev]`, never emits the `workflow_run` event this trigger depends on, so the feature degrades to a silent no-op, not a failure.
272
+ **Consumer-repo acceptance note:** the full happy-path loop (squash-merge → post-merge CI → `workflow_run` → `/bkit-debug` dispatch → fix PR → re-merge) is only exercisable on consumer repos with `bkit-cloud.yml` installed and its dispatch secrets wired (see the cloud-agent auth surfaces in `docs/security.md`). A consumer without `bkit-cloud.yml` installed, or without CI running on `push: branches: [dev]`, never emits the `workflow_run` event this trigger depends on, so the feature degrades to a silent no-op, not a failure.
271
273
 
272
274
  ## Ship gate + bookkeeping
273
275
 
@@ -387,7 +389,7 @@ Use one. Both open PRs for the same packages. `bkit.depUpdater: "none"` skips th
387
389
 
388
390
  **Renovate, self-hosted.** Copy the workflow example. Suspend the Mend App for this repo (Settings → Applications → Renovate → Configure → remove this repo) or both open `renovate/*` PRs. The cron wakes the bot daily; `renovate.json5` `schedule` still gates normal PRs. Do not narrow the cron to weekly, because `osvVulnerabilityAlerts` PRs need the daily wake.
389
391
 
390
- Platform auth is a repo secret `BKIT_GH_TOKEN`, never `GITHUB_TOKEN` (those PRs do not trigger CI, so required checks and automerge never fire). Fine-grained PAT, this repo:
392
+ Platform auth is a repo secret `BKIT_GH_TOKEN`, never `GITHUB_TOKEN` (those PRs do not trigger CI, so required checks and automerge never fire). Use a **fine-grained** PAT when this repo is the only owner-scope bkit touches; use a **classic** PAT when the same token must cover more than one owner — fine-grained PATs cannot span organizations. Fine-grained permissions for this repo:
391
393
 
392
394
  <!-- prettier-ignore -->
393
395
  | Repository permission | Access |
@@ -400,12 +402,7 @@ Platform auth is a repo secret `BKIT_GH_TOKEN`, never `GITHUB_TOKEN` (those PRs
400
402
  | Dependabot alerts | Read |
401
403
  | Metadata | Read-only |
402
404
 
403
- `Commit statuses: Read and write` is what opens the PR. Without it Renovate creates the branch and 403s on commit status. There is no separate Checks permission on a fine-grained PAT. Keep `BKIT_GH_TOKEN` separate from `BKIT_GH_TOKEN_INSTALL` (`read:packages` only). Org-owned tokens cannot read the owner email; set the Actions variable `RENOVATE_GIT_AUTHOR` (for example `Renovate Bot <renovate@your-domain>`).
404
-
405
- **Private package.** `@cbartens/bkit` is on `npm.pkg.github.com`. Lockfile regen resolves it for every bump. Without a read token, regen 401s and CI fails `pnpm install --frozen-lockfile`.
406
-
407
- - Mend: add `BKIT_GH_TOKEN_INSTALL` as a Mend repository secret and tick "used during the scan as an environment variable". Uncomment the `hostRules` `token` line in `renovate.json5`.
408
- - Self-hosted: leave that line commented. The example workflow sets `RENOVATE_HOST_RULES` from the Actions secret. An uncommented Mend-style line adds an empty-token rule and 401s.
405
+ `Commit statuses: Read and write` is what opens the PR. Without it Renovate creates the branch and 403s on commit status. There is no separate Checks permission on a fine-grained PAT. Classic equivalent: scopes `repo`, `workflow`, `security_events` (plus `user:email` for commit authorship). Org-owned tokens cannot read the owner email; set the Actions variable `RENOVATE_GIT_AUTHOR` (for example `Renovate Bot <renovate@your-domain>`).
409
406
 
410
407
  **pnpm 11 on Mend's runner.** A large graph can OOM during `pnpm update --lockfile-only`. The example sets `minimumReleaseAge: "1 day"` and caps `PNPM_WORKERS`. To clear the per-install gate, set `minimumReleaseAge: 0` in `pnpm-workspace.yaml`. Deleting the key does not: pnpm 11 defaults it to 1440. Self-hosted on `ubuntu-latest` has the memory; the freshness setting is still yours to keep or drop.
411
408
 
@@ -17,7 +17,7 @@
17
17
 
18
18
  ## Supply-Chain (GitHub Actions)
19
19
 
20
- Action SHA-pinning and the dependency-update pipeline (Renovate / Dependabot, private-registry read-auth, CVE handling) are CI/CD pipeline rules → canonical home `deployments.md` § Dependency updaters; this section keeps only the security invariant.
20
+ Action SHA-pinning and the dependency-update pipeline (Renovate / Dependabot, CVE handling) are CI/CD pipeline rules → canonical home `deployments.md` § Dependency updaters; this section keeps only the security invariant.
21
21
 
22
22
  **Token isolation:** Renovate PRs use a restricted `GITHUB_TOKEN` with no access to the cloud lane's model-auth secrets (`secrets.ANTHROPIC_API_KEY` / `secrets.OPENCODE_PROVIDER_KEY`) — `bkit-cloud.yml` will not dispatch on them by design. A compromised dependency PR cannot reach agent API credentials.
23
23
 
@@ -89,4 +89,9 @@ playwright/.auth/
89
89
  # Local MCP / agent secrets — never commit
90
90
  .bkit/.env
91
91
 
92
+ # Payload view links — `bkit install` / `upgrade` symlink these into
93
+ # node_modules/@cbartens/bkit; they dangle on a fresh clone or in CI, so never commit.
94
+ .bkit/core
95
+ .bkit/shared
96
+
92
97
  # <!-- bkit:end -->
@@ -55,11 +55,6 @@ if [ "${CLAUDE_CODE_REMOTE:-}" = "true" ] && command -v jq >/dev/null 2>&1; then
55
55
  fi
56
56
 
57
57
  if [ -f pnpm-lock.yaml ] && command -v pnpm >/dev/null 2>&1; then
58
- # Writes the GH Packages auth token into pnpm's user-level config before install,
59
- # alongside the project .npmrc auth token line.
60
- if [ -n "${BKIT_GH_TOKEN_INSTALL:-}" ]; then
61
- pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL" || log "pnpm config set failed (non-blocking)"
62
- fi
63
58
  log "pnpm install --frozen-lockfile"
64
59
  pnpm install --frozen-lockfile --prefer-offline || log "pnpm install failed (non-blocking)"
65
60
  fi
@@ -51,7 +51,7 @@ RUN cd /tmp \
51
51
  && rm -f "vale_${VALE_VERSION}_Linux_64-bit.tar.gz"
52
52
 
53
53
  # pnpm — corepack-pinned to match `packageManager` in package.json.
54
- RUN corepack enable && corepack prepare pnpm@10.34.3 --activate
54
+ RUN corepack enable && corepack prepare pnpm@10.34.4 --activate
55
55
 
56
56
  # --- Consumer extensions ---------------------------------------------------
57
57
  # Add per-repo install steps here. Uncomment / adapt as needed:
@@ -2,5 +2,5 @@
2
2
  "build": {
3
3
  "dockerfile": "Dockerfile"
4
4
  },
5
- "install": "pnpm config set //npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL && pnpm install --frozen-lockfile && ([ ! -f .vale.ini ] || vale sync)"
5
+ "install": "pnpm install --frozen-lockfile && ([ ! -f .vale.ini ] || vale sync)"
6
6
  }
@@ -88,21 +88,6 @@
88
88
  ".agents/skills/**",
89
89
  ],
90
90
 
91
- // Private-registry read auth for `@cbartens/bkit` on npm.pkg.github.com.
92
- // Renovate resolves the whole workspace to regenerate the lockfile and needs
93
- // a read token for this host to do so.
94
- // Mend: uncomment `token` and add BKIT_GH_TOKEN_INSTALL as a Mend repository
95
- // secret with "used during the scan as an environment variable" ticked.
96
- // Self-hosted: leave `token` commented; the example workflow injects
97
- // RENOVATE_HOST_RULES from the Actions secret instead. Do not commit a literal token.
98
- // hostRules: [
99
- // {
100
- // matchHost: "npm.pkg.github.com",
101
- // hostType: "npm",
102
- // token: "{{ secrets.BKIT_GH_TOKEN_INSTALL }}",
103
- // },
104
- // ],
105
-
106
91
  // Caps on open and hourly PRs.
107
92
  prConcurrentLimit: 10,
108
93
  prHourlyLimit: 4,
@@ -43,14 +43,6 @@ jobs:
43
43
  # (PR title for feature-branch pushes vs commit message for direct dev/main pushes)
44
44
  # and docs/testing.md § "CI verbosity" for the full knob list.
45
45
  #
46
- # BKIT_GH_TOKEN_INSTALL is declared at the job level so $BKIT_GH_TOKEN_INSTALL is available to the
47
- # install step's `pnpm config set` (the REQUIRED GH Packages auth — pnpm >=10.34.3
48
- # 401s on a project-.npmrc ${BKIT_GH_TOKEN_INSTALL} env-substitution) and to any later
49
- # pnpm/npx invocation. The committed project .npmrc carries ONLY the @cbartens
50
- # registry mapping; `pnpm config set` writes the shell-expanded literal token into
51
- # pnpm's user-level config before install (works across pnpm 10.x/11.x). The install
52
- # step also keeps its own env: block.
53
- #
54
46
  # NODE_OPTIONS is set HERE, in static YAML, and must NEVER be written to $GITHUB_ENV.
55
47
  # The runner blocklists NODE_OPTIONS for the $GITHUB_ENV / set-env workflow command:
56
48
  # the write is REJECTED with
@@ -63,7 +55,6 @@ jobs:
63
55
  TURBO_LOG_LEVEL: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && 'full' || 'errors-only' }}
64
56
  VERBOSE_CI: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && '1' || '' }}
65
57
  NODE_OPTIONS: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && '--trace-warnings --trace-deprecation' || '' }}
66
- BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
67
58
  steps:
68
59
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
69
60
  with:
@@ -216,13 +207,7 @@ jobs:
216
207
 
217
208
  - name: Install Dependencies
218
209
  if: steps.cache.outputs.skip != 'true'
219
- # Write the GH Packages auth token into pnpm's user-level config before install
220
- # (REQUIRED — pnpm >=10.34.3 401s on a project-.npmrc ${BKIT_GH_TOKEN_INSTALL} ref).
221
- run: |
222
- pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"
223
- pnpm install --frozen-lockfile
224
- env:
225
- BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
210
+ run: pnpm install --frozen-lockfile
226
211
 
227
212
  # Static checks first — they read the source tree and must scan it CLEAN.
228
213
  # Vitest/build run AFTER (below): they write coverage, dist/, and other
@@ -318,7 +303,6 @@ jobs:
318
303
  TURBO_LOG_LEVEL: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && 'full' || 'errors-only' }}
319
304
  VERBOSE_CI: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && '1' || '' }}
320
305
  NODE_OPTIONS: ${{ (contains(github.event.head_commit.message, '[verbose ci]') || contains(github.event.pull_request.title, '[verbose ci]')) && '--trace-warnings --trace-deprecation' || '' }}
321
- BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
322
306
  steps:
323
307
  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
324
308
  with:
@@ -418,11 +402,7 @@ jobs:
418
402
 
419
403
  - name: Install Dependencies
420
404
  if: steps.cache.outputs.skip != 'true'
421
- run: |
422
- pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"
423
- pnpm install --frozen-lockfile
424
- env:
425
- BKIT_GH_TOKEN_INSTALL: ${{ secrets.BKIT_GH_TOKEN_INSTALL }}
405
+ run: pnpm install --frozen-lockfile
426
406
 
427
407
  # bkit-stub:supabase-migrate — REMOTE `db push` belongs in `bkit-tests-migration`, NOT here
428
408
  # and NOT in `bkit-tests-e2e-web`. Prefer the migration-lane stub below
@@ -817,8 +797,11 @@ jobs:
817
797
  # # run_e2e = run_level==full && web_affected_eff. run_live = push dev/main && web_affected_eff (@live stays PUSH-ONLY — real LLM/email side effects; a docs-only/empty [force full] push reaches it via web_affected_eff, NOT off a PR/dispatch).
818
798
  # # run_migration: true when migration/seed/seed-generator paths changed (or workflow_dispatch / no-usable-base → run-to-be-safe). Orthogonal to run_level — a run_level=none run can still need replay. Emits into the plan so migration-lane heavy steps gate per-step (job stays always-on).
819
799
  # - name: Decide Release Mirror # [U] OPTIONAL — one CI run per dev commit. mirror_push_run = pull_request
820
- # # && head.repo.full_name == github.repository && head_ref == 'dev' && base_ref == the default branch
821
- # # (head_ref via env:, injection-safe). True → LAST word in the plan: run_level=none, run_e2e/run_live/
800
+ # # && head.repo.full_name == github.repository && base_ref == the default branch && head_ref is a
801
+ # # promotion branch — 'dev', or 'release/*' when the repo promotes via a release branch (bkit's own
802
+ # # does: main only moves via a release/* → main PR). head_ref via env:, injection-safe. The capstone's
803
+ # # bkit runs mirror resolves the push run BY SHA, so a release/* head with no green dev push run fails
804
+ # # red (exit 3), never silently passes. True → LAST word in the plan: run_level=none, run_e2e/run_live/
822
805
  # # run_migration/web_affected=false, so every lane skips (migration lane included — it is always-on, so
823
806
  # # its replay steps must read run_migration) and the capstone copies the dev push run's verdict (JOB 4).
824
807
  # # The release PR head IS the dev tip that push run is testing; re-testing it doubles the slowest run.
@@ -154,7 +154,6 @@ jobs:
154
154
  ref: dev
155
155
  fetch-depth: 0
156
156
  # The auto-provided GITHUB_TOKEN inherits the `permissions:` block above.
157
- # Do not swap in BKIT_GH_TOKEN_INSTALL — it has no access to the consumer repo.
158
157
  token: ${{ github.token }}
159
158
 
160
159
  - name: Configure git user
@@ -470,7 +469,6 @@ jobs:
470
469
  ref: dev
471
470
  fetch-depth: 0
472
471
  # The auto-provided GITHUB_TOKEN inherits the `permissions:` block above.
473
- # Do not swap in BKIT_GH_TOKEN_INSTALL — it has no access to the consumer repo.
474
472
  token: ${{ github.token }}
475
473
 
476
474
  # Installs the vale binary for bkit-cloud-bootstrap.sh's `vale sync` and the dispatched
@@ -36,7 +36,7 @@ on:
36
36
  - cron: "17 6 * * *"
37
37
 
38
38
  # Least privilege: Renovate authenticates EVERY GitHub operation with BKIT_GH_TOKEN
39
- # below (a fine-grained PAT or App token — NOT GITHUB_TOKEN). The job GITHUB_TOKEN
39
+ # below (a fine-grained or classic PAT, or an App token — NOT GITHUB_TOKEN). The job GITHUB_TOKEN
40
40
  # needs no write scope.
41
41
  permissions:
42
42
  contents: read
@@ -67,13 +67,15 @@ jobs:
67
67
  # then set `token: ${{ steps.app-token.outputs.token }}` below.
68
68
  - uses: renovatebot/github-action@dd5302ec17783b2fc721b19ae7209b57b1587765 # v46.1.17
69
69
  with:
70
- # Fine-grained PAT secret (default). Repository permissions (this repo):
70
+ # PAT secret (default). FINE-GRAINED repository permissions (this repo):
71
71
  # Contents: Read and write · Pull requests: Read and write ·
72
72
  # Workflows: Read and write (the github-actions manager edits
73
73
  # .github/workflows/* SHAs) · Issues: Read and write (Dependency Dashboard) ·
74
74
  # Dependabot alerts: Read (GitHub's vulnerability feed) · Metadata: Read-only.
75
- # (Personal-account tokens only: Account permission "Email addresses: Read" lets
76
- # Renovate use your verified email as the git author — org-owned tokens have no
75
+ # CLASSIC alternative — when one token must span owners (fine-grained PATs cannot):
76
+ # scopes `repo` · `workflow` · `security_events` (+ `user:email` for authorship).
77
+ # (Personal-account fine-grained tokens only: Account permission "Email addresses: Read"
78
+ # lets Renovate use your verified email as the git author — org-owned tokens have no
77
79
  # such permission, so set RENOVATE_GIT_AUTHOR below instead.)
78
80
  token: ${{ secrets.BKIT_GH_TOKEN }}
79
81
  env:
@@ -82,7 +84,7 @@ jobs:
82
84
  RENOVATE_AUTODISCOVER: "false"
83
85
  RENOVATE_PLATFORM: github
84
86
  # Commit author for Renovate's branches. Optional but recommended on ORG repos:
85
- # org-owned fine-grained PATs cannot grant "Email addresses", so Renovate can't
87
+ # org-owned tokens cannot grant "Email addresses", so Renovate can't
86
88
  # read your email and falls back to the Mend bot author (Unverified commits).
87
89
  # Set the repo variable RENOVATE_GIT_AUTHOR (Settings -> Secrets and variables ->
88
90
  # Actions -> Variables), e.g. `Renovate Bot <renovate@your-domain>`. Leave the
@@ -95,11 +97,6 @@ jobs:
95
97
  # allowedEnv") and Renovate does nothing. Mend allows these via its safeEnv
96
98
  # preset; self-hosted must set it explicitly. Glob covers any future PNPM_* var.
97
99
  RENOVATE_ALLOWED_ENV: "PNPM_*"
98
- # Private-registry read auth for the restricted @cbartens/bkit package.
99
- # Leave the hostRules token line in renovate.json5 commented. BKIT_GH_TOKEN_INSTALL
100
- # (read:packages) is a repo Actions secret. See docs/deployments.md § Dependency updaters.
101
- RENOVATE_HOST_RULES: >-
102
- [{"matchHost":"npm.pkg.github.com","hostType":"npm","token":"${{ secrets.BKIT_GH_TOKEN_INSTALL }}"}]
103
100
  LOG_LEVEL: ${{ inputs.logLevel || 'info' }}
104
101
  RENOVATE_DRY_RUN: ${{ inputs.dryRun || 'null' }}
105
102
  # This env block declares NO ANTHROPIC_API_KEY / BKIT_LINEAR_API_KEY