@cbartens/bkit 5.3.0 → 5.4.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 (128) hide show
  1. package/.bkit/README.md +3 -2
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +8 -2
  4. package/.bkit/core/.bkit/README.md +2 -1
  5. package/.bkit/core/.bkit/cloud.md +33 -33
  6. package/.bkit/core/.bkit/comparison.md +1 -1
  7. package/.bkit/core/.bkit/install.md +6 -5
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +4 -3
  10. package/.bkit/core/.bkit/prompts.md +4 -3
  11. package/.bkit/core/.bkit/providers.md +1 -1
  12. package/.bkit/core/.bkit/templates.md +35 -5
  13. package/.bkit/core/.bkit/trackers.md +7 -8
  14. package/.bkit/core/.bkit/workflows.md +106 -86
  15. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  16. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  17. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  23. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  25. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  26. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  28. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  29. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  30. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  32. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  34. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  36. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  37. package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
  38. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  39. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  40. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  43. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  44. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  47. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  48. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  49. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  50. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  51. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -0
  52. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  53. package/.bkit/core/engine/cli.ts +22 -15
  54. package/.bkit/core/engine/commands/comply.ts +25 -16
  55. package/.bkit/core/engine/commands/install/install.ts +11 -4
  56. package/.bkit/core/engine/commands/land.ts +156 -0
  57. package/.bkit/core/engine/commands/lib.ts +10 -8
  58. package/.bkit/core/engine/commands/registry.ts +2 -0
  59. package/.bkit/core/engine/commands/tips.ts +7 -3
  60. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  61. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  62. package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
  63. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  64. package/.bkit/core/engine/commands/workflow/prs.ts +11 -2
  65. package/.bkit/core/engine/commands/workflow/roadmap.ts +48 -53
  66. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  67. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  68. package/.bkit/core/engine/commands/workflow/steps.ts +24 -15
  69. package/.bkit/core/engine/commands/workflow/workflows.ts +433 -265
  70. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  71. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  72. package/.bkit/core/engine/install/modules/core.ts +15 -0
  73. package/.bkit/core/engine/install/placeholders.ts +13 -17
  74. package/.bkit/core/engine/shared/settings.ts +8 -0
  75. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  76. package/.bkit/core/prompts/bkit-audit-generate.md +47 -4
  77. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -1
  78. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -1
  79. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
  80. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -1
  81. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -1
  82. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +3 -3
  83. package/.bkit/core/workflows/bkit-auto.md +2 -2
  84. package/.bkit/core/workflows/bkit-build.md +7 -7
  85. package/.bkit/core/workflows/bkit-debug.md +11 -11
  86. package/.bkit/core/workflows/bkit-design.md +20 -11
  87. package/.bkit/core/workflows/bkit-plan.md +23 -13
  88. package/.bkit/core/workflows/bkit-ship.md +82 -93
  89. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  90. package/.bkit/shared/.claude/settings.json +1 -0
  91. package/.bkit/shared/docs/deployments.md +29 -25
  92. package/.bkit/shared/gitignore +1 -2
  93. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  94. package/.bkit/templates/.github/workflows/bkit-ci.yml +7 -2
  95. package/.bkit/templates/.husky/pre-commit +6 -0
  96. package/.bkit/templates/.husky/pre-push +7 -0
  97. package/.bkit/templates/.lintstagedrc.json +5 -1
  98. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  99. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  100. package/CHANGELOG.md +48 -0
  101. package/README.md +97 -96
  102. package/dist/checks/status-holes.js +0 -1
  103. package/dist/checks/tips/catalogue.js +14 -0
  104. package/dist/checks/tips/index.js +44 -28
  105. package/dist/cli.js +22 -16
  106. package/dist/commands/comply.js +20 -13
  107. package/dist/commands/install/install.js +10 -4
  108. package/dist/commands/land.js +129 -0
  109. package/dist/commands/lib.js +9 -6
  110. package/dist/commands/registry.js +2 -0
  111. package/dist/commands/tips.js +7 -3
  112. package/dist/commands/workflow/branches.js +300 -243
  113. package/dist/commands/workflow/disk.js +452 -0
  114. package/dist/commands/workflow/issues.js +63 -27
  115. package/dist/commands/workflow/locks.js +35 -130
  116. package/dist/commands/workflow/prs.js +5 -2
  117. package/dist/commands/workflow/roadmap.js +49 -56
  118. package/dist/commands/workflow/runtime.js +3 -2
  119. package/dist/commands/workflow/status.js +32 -12
  120. package/dist/commands/workflow/steps.js +18 -11
  121. package/dist/commands/workflow/workflows.js +388 -247
  122. package/dist/commands/workflow/workstreams.js +3 -2
  123. package/dist/commands/workflow/worktrees.js +11 -1
  124. package/dist/install/modules/core.js +13 -0
  125. package/dist/install/placeholders.js +13 -19
  126. package/dist/shared/settings.js +5 -0
  127. package/dist/shared/timeouts.js +8 -7
  128. package/package.json +1 -1
@@ -6,6 +6,7 @@
6
6
  "Bash(*)",
7
7
  "mcp__github__*",
8
8
  "mcp__claude_ai_Linear__*",
9
+ "mcp__linear__*",
9
10
  "WebSearch",
10
11
  "Bash(git push --force-with-lease:*)",
11
12
  "Read(./.env.example)",
@@ -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).
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).
57
56
  - On `revert-*` branches pre-push drops only the **unit lane** (`bkit:gate:static` in place of `bkit:gate:static-unit`), so the static lane and the bkit drift gate still run → revert PR pushable when source state transitionally inconsistent.
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
 
@@ -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.
@@ -300,7 +300,7 @@ To unwind a bad ship surface (the gate command, managed config, or rewritten `bk
300
300
  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
301
  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
302
 
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).
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`) → 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
304
 
305
305
  ## Smoke trigger plumbing
306
306
 
@@ -340,6 +340,8 @@ Latent until the first build-time DB read lands, so flag it in review when one i
340
340
 
341
341
  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
342
 
343
+ 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).
344
+
343
345
  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
346
 
345
347
  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 +415,8 @@ Use one. Both open PRs for the same packages. `bkit.depUpdater: "none"` skips th
413
415
 
414
416
  **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
417
 
418
+ **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.
419
+
416
420
  **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
421
 
418
422
  **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.
@@ -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>
@@ -827,7 +827,9 @@ jobs:
827
827
  # bkit-tests-scope: runs-on: ubuntu-latest; timeout-minutes: 2; outputs: { plan: ${{ steps.scope.outputs.plan }} }
828
828
  # steps:
829
829
  # - 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)
830
+ # - name: Install Turbo # [M] bare global install, ~10-15s; no pnpm install. Version READ from
831
+ # # package.json, which pins turbo EXACTLY — never typed here, or this lane drifts from every
832
+ # # install-bearing lane: npm i -g "turbo@$(node -p "require('./package.json').devDependencies.turbo")"
831
833
  # - name: Resolve Base Ref # [M] push base = the branch's last green run; shipped:
832
834
  # # scripts/ci/lanes/resolve-push-base.mjs (falls back to github.event.before). deployments.md
833
835
  # # § One run per branch or pull request.
@@ -1090,7 +1092,10 @@ jobs:
1090
1092
  # block queues on {{DEFAULT_BRANCH}} too. Runs BEFORE the E2E / @live lanes: each of those needs: it and
1091
1093
  # refuses unless production serves this run's build (by deployment id). Promotes the EXACT deployment_id
1092
1094
  # 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
1095
+ # the body says this id is already current production. Before promoting it refuses, moving nothing, when
1096
+ # the id equals repo variable ROLLED_BACK_DEPLOYMENT_ID (set by the rollback) or when this commit is neither
1097
+ # production's commit nor a descendant of it (e.g. GitHub compare API status not ahead / identical), so a
1098
+ # re-run of an old run never moves production back. A red job means the release did not happen; the
1094
1099
  # previous deployment stays live. On a default-branch push the capstone needs: it, so a skipped or failed
1095
1100
  # deploy reds bkit-tests-check.
1096
1101
  # The host must not auto-build the default branch, and any "hold promotion until a check passes"
@@ -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
@@ -101,3 +101,10 @@ fi
101
101
  # Outside the gate scripts: it validates the bkit install, not your source.
102
102
  # Fix: `pnpm bkit install`, stage the regenerated files, commit, push.
103
103
  pnpm bkit check < /dev/null
104
+
105
+ # disk prune — keep this block last, so it runs only once every gate above passed. Starts
106
+ # your max cleanup steps (`bkit disk prune`, .bkit/templates.md § Disk prune) in the
107
+ # background, at most once a day, or hourly while free disk is under bkit.disk.minFreeGb;
108
+ # with no step files it does nothing. Not a gate: a failure warns and the push goes on.
109
+ pnpm -s bkit disk prune --mode=max --auto < /dev/null > /dev/null ||
110
+ echo "[pre-push] WARN: disk prune failed; push continues" >&2
@@ -1,3 +1,7 @@
1
1
  {
2
- "*": "prettier --write --ignore-unknown"
2
+ "docs/{plans,audits}/**/*.md": [
3
+ "node scripts/prettier/bkit-insert-ignore.mjs",
4
+ "prettier --write --ignore-unknown"
5
+ ],
6
+ "!(docs/{plans,audits}/**/*.md)": "prettier --write --ignore-unknown"
3
7
  }
@@ -0,0 +1,197 @@
1
+ // Example. Copy to ~/.config/bkit/disk-prune.mjs (`$XDG_CONFIG_HOME/bkit/` when set) and own
2
+ // it. bkit install does not write this file and does not overwrite a copy.
3
+ /**
4
+ * disk-prune.mjs — this machine's cleanup steps for `bkit disk prune`: tools every repo on
5
+ * the machine shares (Docker, the pnpm store, Xcode, Gradle, simulators). bkit deletes
6
+ * nothing itself: it runs only the steps listed here and in each checkout's
7
+ * `scripts/cleanup/bkit-disk-prune.mjs`.
8
+ *
9
+ * Steps run from the home folder, one at a time, with the same shape as the checkout file:
10
+ * `name`, `mode` ("min" | "max"; `max` runs the `min` steps too), `run` (shell command or
11
+ * function), optional `skip` and `paths` (what `--dry-run` sizes: the most the step can free;
12
+ * leave it out when that misleads). A step whose tool is not installed skips itself.
13
+ *
14
+ * Keep a step only when what it deletes comes back by itself. Deliberately left out — add
15
+ * them yourself only if you accept the cost:
16
+ * - Docker named volumes (`docker volume prune -a`): local databases live there
17
+ * - whole runtimes or SDKs (Xcode, Android system images, iOS simulator runtimes, Node
18
+ * versions): gigabytes to download and a manual step to reinstall
19
+ * - deleting the whole pnpm store: `node_modules` hard-link into it, so it frees nothing
20
+ * while any checkout is installed; `pnpm store prune` frees what can be freed
21
+ */
22
+
23
+ import { spawnSync } from "node:child_process";
24
+ import os from "node:os";
25
+
26
+ /** True when `tool` is on PATH. */
27
+ const has = (tool) => spawnSync("sh", ["-c", `command -v ${tool}`]).status === 0;
28
+ /** True when a process whose full command line matches `pattern` is running. */
29
+ const running = (pattern) => spawnSync("pgrep", ["-f", pattern]).status === 0;
30
+ const missing = (tool) => !has(tool) && `${tool} is not installed`;
31
+ const dockerDown = () =>
32
+ missing("docker") ||
33
+ (spawnSync("docker", ["info"], { stdio: "ignore" }).status !== 0 && "Docker is not running");
34
+ const notMac = () => os.platform() !== "darwin" && "not macOS";
35
+
36
+ /** Docker's major version; 0 when unreadable. */
37
+ function dockerMajor() {
38
+ const r = spawnSync("docker", ["version", "--format", "{{.Server.Version}}"], {
39
+ encoding: "utf8",
40
+ });
41
+ return r.status === 0 ? Number(r.stdout.split(".")[0]) || 0 : 0;
42
+ }
43
+
44
+ // Name the simulators and emulators you can do without; empty = none deleted. Booted or
45
+ // running ones are skipped. Find names with `xcrun simctl list devices` and
46
+ // `emulator -list-avds`.
47
+ const SIMULATORS = [];
48
+ const EMULATORS = [];
49
+
50
+ export default [
51
+ // --- min: stale, cheap ---------------------------------------------------
52
+ {
53
+ // Comes back: the next `docker build` or `docker pull`.
54
+ name: "Docker dangling images",
55
+ mode: "min",
56
+ skip: dockerDown,
57
+ run: "docker image prune -f",
58
+ },
59
+ {
60
+ // Comes back: the next `docker build`, slower once.
61
+ name: "Docker build cache older than 7 days",
62
+ mode: "min",
63
+ skip: dockerDown,
64
+ run: "docker builder prune -f --filter until=168h",
65
+ },
66
+ {
67
+ // Comes back: never needed — no container uses them. Docker 23+ prunes only anonymous
68
+ // volumes; older Docker would also take named volumes, so the step skips there.
69
+ name: "Docker anonymous volumes",
70
+ mode: "min",
71
+ skip: () => dockerDown() || (dockerMajor() < 23 && "Docker older than 23 prunes named volumes"),
72
+ run: "docker volume prune -f",
73
+ },
74
+ {
75
+ // Comes back: the next `pnpm install` that needs a removed package. No `paths`: the
76
+ // store's size is far more than a prune frees.
77
+ name: "pnpm store packages no project uses",
78
+ mode: "min",
79
+ skip: () =>
80
+ missing("pnpm") || (running("pnpm (install|i|add|update)( |$)") && "pnpm is installing"),
81
+ run: "pnpm store prune",
82
+ },
83
+ {
84
+ // Comes back: never needed — these simulators belong to runtimes no longer installed.
85
+ name: "iOS simulators whose runtime is gone",
86
+ mode: "min",
87
+ skip: () => notMac() || missing("xcrun"),
88
+ run: "xcrun simctl delete unavailable",
89
+ },
90
+ {
91
+ // Comes back: the next `npm install` that needs a removed entry.
92
+ name: "npm cache: drop corrupt and unused entries",
93
+ mode: "min",
94
+ paths: ["~/.npm/_cacache"],
95
+ skip: () => missing("npm"),
96
+ run: "npm cache verify",
97
+ },
98
+
99
+ // --- max: everything that comes back by itself -------------------------
100
+ {
101
+ // Comes back: the next `docker pull` or `docker build`. Containers you have stopped
102
+ // keep their images; `supabase stop` removes its containers, so its images go too and
103
+ // `supabase start` pulls them again.
104
+ name: "Docker images no container uses",
105
+ mode: "max",
106
+ skip: dockerDown,
107
+ run: "docker image prune -a -f",
108
+ },
109
+ {
110
+ // Comes back: the next `docker build`, slower once.
111
+ name: "All of the Docker build cache",
112
+ mode: "max",
113
+ skip: dockerDown,
114
+ run: "docker builder prune -a -f",
115
+ },
116
+ {
117
+ // Comes back: the next Xcode build, slower once.
118
+ name: "Xcode DerivedData",
119
+ mode: "max",
120
+ paths: ["~/Library/Developer/Xcode/DerivedData"],
121
+ skip: () => notMac() || (running("xcodebuild") && "xcodebuild is running"),
122
+ run: 'rm -rf "$HOME/Library/Developer/Xcode/DerivedData"',
123
+ },
124
+ {
125
+ // Comes back: the next Gradle build downloads and rebuilds what it needs.
126
+ name: "Gradle caches",
127
+ mode: "max",
128
+ paths: ["~/.gradle/caches"],
129
+ skip: () => running("GradleDaemon") && "a Gradle daemon is running (`gradle --stop`)",
130
+ run: 'rm -rf "$HOME/.gradle/caches"',
131
+ },
132
+ {
133
+ // Comes back: an emulator cold-boots once, then saves a fresh snapshot.
134
+ name: "Android emulator snapshots",
135
+ mode: "max",
136
+ paths: ["~/.android/avd/*.avd/snapshots"],
137
+ skip: () => running("qemu-system") && "an Android emulator is running",
138
+ run: 'rm -rf "$HOME"/.android/avd/*.avd/snapshots',
139
+ },
140
+ {
141
+ // Comes back: recreate with `xcrun simctl create` (or Xcode → Devices) when needed.
142
+ name: "iOS simulators named in SIMULATORS",
143
+ mode: "max",
144
+ skip: () => notMac() || missing("xcrun") || (SIMULATORS.length === 0 && "SIMULATORS is empty"),
145
+ run: ({ log }) => {
146
+ const booted = spawnSync("xcrun", ["simctl", "list", "devices", "booted"], {
147
+ encoding: "utf8",
148
+ }).stdout;
149
+ for (const name of SIMULATORS) {
150
+ if (booted.includes(`${name} (`)) {
151
+ log(`kept ${name}: booted`);
152
+ continue;
153
+ }
154
+ const r = spawnSync("xcrun", ["simctl", "delete", name], { encoding: "utf8" });
155
+ log(`${name}: ${r.status === 0 ? "deleted" : "not deleted"}`);
156
+ }
157
+ },
158
+ },
159
+ {
160
+ // Comes back: recreate with `avdmanager create avd` (or Android Studio) when needed.
161
+ name: "Android emulators named in EMULATORS",
162
+ mode: "max",
163
+ skip: () => missing("avdmanager") || (EMULATORS.length === 0 && "EMULATORS is empty"),
164
+ run: ({ log }) => {
165
+ for (const name of EMULATORS) {
166
+ if (running(`-avd ${name}( |$)`)) {
167
+ log(`kept ${name}: running`);
168
+ continue;
169
+ }
170
+ const r = spawnSync("avdmanager", ["delete", "avd", "-n", name], { encoding: "utf8" });
171
+ log(`${name}: ${r.status === 0 ? "deleted" : "not deleted"}`);
172
+ }
173
+ },
174
+ },
175
+ {
176
+ // Comes back: the next `npm install` / `npx` downloads what it needs.
177
+ name: "All of the npm cache",
178
+ mode: "max",
179
+ paths: ["~/.npm/_cacache"],
180
+ skip: () => missing("npm"),
181
+ run: "npm cache clean --force",
182
+ },
183
+ {
184
+ // Comes back: the next `uv` / `uvx` run downloads what it needs.
185
+ name: "uv cache",
186
+ mode: "max",
187
+ skip: () => missing("uv"),
188
+ run: "uv cache clean",
189
+ },
190
+ {
191
+ // Comes back: Homebrew downloads again only to reinstall or upgrade.
192
+ name: "Homebrew downloads and old versions",
193
+ mode: "max",
194
+ skip: () => missing("brew"),
195
+ run: "brew cleanup --prune=all",
196
+ },
197
+ ];
@@ -0,0 +1,164 @@
1
+ // Example. Copy into scripts/cleanup/ and own it. bkit install does not write this file
2
+ // and does not overwrite a copy.
3
+ /**
4
+ * bkit-disk-prune.mjs — this checkout's cleanup steps for `bkit disk prune`. bkit deletes
5
+ * nothing itself: it runs only the steps listed here and in your machine file
6
+ * (`~/.config/bkit/disk-prune.mjs`, from `bkit-disk-prune.machine.mjs`).
7
+ *
8
+ * Steps run from the top of the checkout, one at a time. Each step:
9
+ * name what it frees, shown in the log
10
+ * mode "min" (stale, cheap; runs from pre-commit) or "max" (everything that comes back by
11
+ * itself; runs after the pre-push gates pass and before a worktree is made on a low
12
+ * disk). `max` runs the `min` steps too.
13
+ * run a shell command (`sh -c`) or a function `({ cwd, log, note }) => …`; non-zero exit
14
+ * or a throw = failed, logged, the next step still runs. `note(text)` = something
15
+ * only a person can decide; `bkit tips` lists it until the next sweep
16
+ * skip optional; a shell command (exit 0 = skip) or a function returning a reason to skip
17
+ * paths optional; what `bkit disk prune --dry-run` sizes, the most the step can free
18
+ * (relative, `~/…`, or globs)
19
+ *
20
+ * Keep a step only when what it deletes comes back by itself. Edit, add or drop freely:
21
+ * paths below assume a monorepo with apps under `apps/`.
22
+ */
23
+
24
+ import { spawnSync } from "node:child_process";
25
+ import fs from "node:fs";
26
+ import path from "node:path";
27
+
28
+ /** True when a process whose full command line matches `pattern` is running. */
29
+ const running = (pattern) => spawnSync("pgrep", ["-f", pattern]).status === 0;
30
+
31
+ const turboRunning = () => running("(^|/)turbo( |$)") && "turbo is running";
32
+ const nextRunning = () =>
33
+ running("(^|/)next( (dev|build|start)|-server)") && "a Next.js server or build is running";
34
+
35
+ /** `text` as JSON: `{ ok: true, value }`, or `{ ok: false, error }` saying why not. */
36
+ function parseJson(text) {
37
+ try {
38
+ return { ok: true, value: JSON.parse(text) };
39
+ } catch (err) {
40
+ return { ok: false, error: err instanceof Error ? err.message : String(err) };
41
+ }
42
+ }
43
+
44
+ /** Days since `wt`'s last commit; Infinity when unreadable. */
45
+ function idleDays(wt) {
46
+ const r = spawnSync("git", ["-C", wt, "log", "-1", "--format=%ct"], { encoding: "utf8" });
47
+ const at = Number(r.stdout.trim());
48
+ return r.status === 0 && at > 0 ? (Date.now() / 1000 - at) / 86400 : Infinity;
49
+ }
50
+
51
+ /**
52
+ * True when a merged pull request's head is exactly `sha`: a squash merge leaves the
53
+ * branch's own commits on no remote. Needs `gh`; false when it cannot answer.
54
+ */
55
+ function mergedPrAt(cwd, branch, sha) {
56
+ if (branch === "") return false;
57
+ const r = spawnSync(
58
+ "gh",
59
+ ["pr", "list", "--head", branch, "--state", "merged", "--json", "headRefOid"],
60
+ { cwd, encoding: "utf8" },
61
+ );
62
+ const prs = r.status === 0 ? parseJson(r.stdout) : { ok: false };
63
+ return prs.ok && Array.isArray(prs.value) && prs.value.some((pr) => pr.headRefOid === sha);
64
+ }
65
+
66
+ /**
67
+ * Leftover worktree `wt` (named `fid`): `{ keep }` while in use, `{ note }` when only a
68
+ * person can tell, else `{}` — removing it loses nothing.
69
+ */
70
+ function judge(cwd, wt, fid) {
71
+ const git = (...args) => spawnSync("git", ["-C", wt, ...args], { encoding: "utf8" });
72
+ if (fs.globSync(path.join(cwd, "docs/plans/*/logs", fid, ".lock")).length > 0)
73
+ return { keep: "a bkit workflow holds its lock" };
74
+ if (idleDays(wt) < 2) return { keep: "committed to in the last 2 days" };
75
+ const status = git("status", "--porcelain");
76
+ if (status.status !== 0) return { note: "not a git worktree; delete the folder if unneeded" };
77
+ if (status.stdout.trim() !== "")
78
+ return { note: `uncommitted or untracked files (\`git -C .worktrees/${fid} status\`)` };
79
+ if (git("rev-list", "HEAD", "--not", "--remotes").stdout.trim() !== "") {
80
+ const branch = git("branch", "--show-current").stdout.trim();
81
+ const sha = git("rev-parse", "HEAD").stdout.trim();
82
+ if (!mergedPrAt(cwd, branch, sha))
83
+ return { note: "commits on no remote branch, and no merged pull request ends at HEAD" };
84
+ }
85
+ return {};
86
+ }
87
+
88
+ /** Remove worktree `wt`; null when gone, else why not. */
89
+ function removeWorktree(cwd, wt, fid) {
90
+ const r = spawnSync("pnpm", ["-s", "bkit", "worktrees", "remove", `--fid=${fid}`], {
91
+ cwd,
92
+ encoding: "utf8",
93
+ });
94
+ const parsed = parseJson(r.stdout);
95
+ if (!parsed.ok) return `bkit worktrees remove failed (exit ${r.status}; output: ${parsed.error})`;
96
+ const out = parsed.value;
97
+ if (out?.removed === true) return null;
98
+ if (out?.reason !== "not-owned")
99
+ return `bkit worktrees remove failed (${out?.reason ?? `exit ${r.status}`})`;
100
+ // No workflow made it, so bkit leaves it; nothing in it is lost, so plain git removes it.
101
+ const g = spawnSync("git", ["-C", cwd, "worktree", "remove", wt], { encoding: "utf8" });
102
+ return g.status === 0 ? null : `git worktree remove failed: ${g.stderr.trim()}`;
103
+ }
104
+
105
+ export default [
106
+ {
107
+ // Comes back: the next build re-runs the tasks it needs.
108
+ name: "Turborepo cache entries untouched for 7 days",
109
+ mode: "min",
110
+ paths: [".turbo/cache"],
111
+ skip: turboRunning,
112
+ run: "[ ! -d .turbo/cache ] || find .turbo/cache -type f -mtime +7 -delete",
113
+ },
114
+ {
115
+ // Comes back: the next `next build` / `next dev`.
116
+ name: "Next.js cache entries untouched for 7 days",
117
+ mode: "min",
118
+ paths: ["apps/*/.next/cache"],
119
+ skip: nextRunning,
120
+ run: 'for d in apps/*/.next/cache; do [ ! -d "$d" ] || find "$d" -type f -mtime +7 -delete; done',
121
+ },
122
+ {
123
+ // Comes back: the next build, slower once.
124
+ name: "All of the Turborepo cache",
125
+ mode: "max",
126
+ paths: [".turbo/cache"],
127
+ skip: turboRunning,
128
+ run: "rm -rf .turbo/cache",
129
+ },
130
+ {
131
+ // Comes back: the next web, Android or iOS build.
132
+ name: "Next.js caches and native build output",
133
+ mode: "max",
134
+ paths: ["apps/*/.next/cache", "apps/*/android/app/build", "apps/*/ios/build"],
135
+ skip: () =>
136
+ nextRunning() || (running("GradleDaemon|xcodebuild") && "a Gradle or Xcode build is running"),
137
+ run: "rm -rf apps/*/.next/cache apps/*/android/app/build apps/*/ios/build",
138
+ },
139
+ {
140
+ // Comes back: `bkit worktrees setup` re-creates a worktree from its branch, and
141
+ // reinstalls its node_modules. Removed only when nothing is lost: clean, and every commit
142
+ // on a remote or at the head of a merged pull request (`gh`). Ignored files (a copied
143
+ // `.env`) go with it; branches stay. Kept silently: a workflow's lock, a commit in the
144
+ // last 2 days. Anything else → a note `bkit tips` lists, for a person to decide.
145
+ name: "Leftover agent worktrees nothing would be lost from",
146
+ mode: "max",
147
+ paths: [".worktrees/*"],
148
+ run: ({ cwd, log, note }) => {
149
+ const root = path.join(cwd, ".worktrees");
150
+ if (!fs.existsSync(root)) return;
151
+ for (const fid of fs.readdirSync(root)) {
152
+ const wt = path.join(root, fid);
153
+ const v = judge(cwd, wt, fid);
154
+ if (v.keep) log(`kept .worktrees/${fid}: ${v.keep}`);
155
+ else if (v.note) note(`.worktrees/${fid}: ${v.note}`);
156
+ else {
157
+ const failed = removeWorktree(cwd, wt, fid);
158
+ if (failed === null) log(`.worktrees/${fid}: removed`);
159
+ else note(`.worktrees/${fid}: ${failed}`);
160
+ }
161
+ }
162
+ },
163
+ },
164
+ ];