@cbartens/bkit 5.2.2 → 5.2.4

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 (100) hide show
  1. package/.bkit/README.md +4 -2
  2. package/.bkit/core/.agents/context.md +2 -2
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +7 -1
  4. package/.bkit/core/.bkit/README.md +3 -1
  5. package/.bkit/core/.bkit/comparison.md +114 -45
  6. package/.bkit/core/.bkit/install.md +6 -6
  7. package/.bkit/core/.bkit/jsonl.md +3 -3
  8. package/.bkit/core/.bkit/prompts.md +6 -5
  9. package/.bkit/core/.bkit/providers.md +5 -4
  10. package/.bkit/core/.bkit/templates.md +30 -11
  11. package/.bkit/core/.bkit/workflows.md +14 -7
  12. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +5 -1
  13. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -2
  14. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +13 -2
  15. package/.bkit/core/docs/templates/bkit-audit-adoption.md +13 -2
  16. package/.bkit/core/docs/templates/bkit-audit-agents.md +13 -2
  17. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +13 -2
  18. package/.bkit/core/docs/templates/bkit-audit-analytics.md +13 -2
  19. package/.bkit/core/docs/templates/bkit-audit-annotations.md +15 -4
  20. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +13 -2
  21. package/.bkit/core/docs/templates/bkit-audit-app-store.md +13 -2
  22. package/.bkit/core/docs/templates/bkit-audit-architecture.md +13 -2
  23. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +13 -2
  24. package/.bkit/core/docs/templates/bkit-audit-config.md +13 -2
  25. package/.bkit/core/docs/templates/bkit-audit-cost.md +14 -3
  26. package/.bkit/core/docs/templates/bkit-audit-coverage.md +13 -2
  27. package/.bkit/core/docs/templates/bkit-audit-database.md +13 -2
  28. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +13 -2
  29. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +13 -2
  30. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +13 -2
  31. package/.bkit/core/docs/templates/bkit-audit-documentation.md +13 -2
  32. package/.bkit/core/docs/templates/bkit-audit-duplication.md +13 -2
  33. package/.bkit/core/docs/templates/bkit-audit-failures.md +14 -3
  34. package/.bkit/core/docs/templates/bkit-audit-flakes.md +15 -4
  35. package/.bkit/core/docs/templates/bkit-audit-gates.md +13 -2
  36. package/.bkit/core/docs/templates/bkit-audit-issues.md +13 -2
  37. package/.bkit/core/docs/templates/bkit-audit-llm.md +13 -2
  38. package/.bkit/core/docs/templates/bkit-audit-logs.md +25 -13
  39. package/.bkit/core/docs/templates/bkit-audit-models.md +13 -2
  40. package/.bkit/core/docs/templates/bkit-audit-privacy.md +13 -2
  41. package/.bkit/core/docs/templates/bkit-audit-prompts.md +13 -2
  42. package/.bkit/core/docs/templates/bkit-audit-red-team.md +14 -3
  43. package/.bkit/core/docs/templates/bkit-audit-reliability.md +14 -3
  44. package/.bkit/core/docs/templates/bkit-audit-repo.md +14 -3
  45. package/.bkit/core/docs/templates/bkit-audit-security.md +15 -4
  46. package/.bkit/core/docs/templates/bkit-audit-slop.md +13 -2
  47. package/.bkit/core/docs/templates/bkit-audit-testing.md +14 -3
  48. package/.bkit/core/docs/templates/bkit-audit-usability.md +13 -2
  49. package/.bkit/core/docs/templates/bkit-plan.md +1 -1
  50. package/.bkit/core/engine/checks/tips/catalogue.ts +10 -0
  51. package/.bkit/core/engine/commands/install/check.ts +3 -11
  52. package/.bkit/core/engine/commands/install/doctor.ts +2 -3
  53. package/.bkit/core/engine/commands/install/uninstall.ts +60 -44
  54. package/.bkit/core/engine/commands/install/upgrade.ts +13 -11
  55. package/.bkit/core/engine/commands/workflow/branches.ts +72 -9
  56. package/.bkit/core/engine/commands/workflow/repo.ts +16 -2
  57. package/.bkit/core/engine/commands/workflow/workflows.ts +4 -3
  58. package/.bkit/core/engine/install/hosts.ts +14 -4
  59. package/.bkit/core/engine/ledgers/telemetry.ts +3 -4
  60. package/.bkit/core/engine/shared/bkit-latest.ts +164 -0
  61. package/.bkit/core/engine/shared/timeouts.ts +6 -0
  62. package/.bkit/core/hooks/guardrails-read.js +4 -9
  63. package/.bkit/core/hooks/guardrails-tiers.js +312 -28
  64. package/.bkit/core/prompts/bkit-audit-generate.md +21 -5
  65. package/.bkit/core/workflows/bkit-build.md +1 -1
  66. package/.bkit/core/workflows/bkit-debug.md +1 -1
  67. package/.bkit/core/workflows/bkit-design.md +1 -1
  68. package/.bkit/core/workflows/bkit-plan.md +1 -1
  69. package/.bkit/core/workflows/bkit-ship.md +1 -1
  70. package/.bkit/shared/.claude/settings.json +19 -0
  71. package/.bkit/shared/.opencode/opencode.json +21 -1
  72. package/.bkit/shared/docs/deployments.md +14 -0
  73. package/.bkit/templates/.github/workflows/bkit-ci.yml +9 -0
  74. package/.bkit/templates/.husky/pre-push +7 -0
  75. package/.bkit/templates/context/bkit-cloudrun.md +28 -19
  76. package/.bkit/templates/context/bkit-expo.md +30 -13
  77. package/.bkit/templates/context/bkit-inngest.md +54 -17
  78. package/.bkit/templates/context/bkit-resend.md +36 -8
  79. package/.bkit/templates/context/bkit-sentry.md +11 -4
  80. package/.bkit/templates/context/bkit-stripe.md +39 -22
  81. package/.bkit/templates/context/bkit-supabase.md +45 -20
  82. package/.bkit/templates/context/bkit-vercel.md +45 -16
  83. package/.bkit/templates/scripts/ci/accepted-advisories.json +7 -0
  84. package/.bkit/templates/scripts/ci/check-dependency-audit.mjs +200 -0
  85. package/.bkit/templates/scripts/ci/check-dependency-audit.test.mjs +127 -0
  86. package/.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs +115 -0
  87. package/CHANGELOG.md +56 -0
  88. package/README.md +76 -20
  89. package/dist/checks/tips/catalogue.js +9 -0
  90. package/dist/commands/install/check.js +3 -15
  91. package/dist/commands/install/doctor.js +2 -1
  92. package/dist/commands/install/uninstall.js +52 -45
  93. package/dist/commands/install/upgrade.js +13 -11
  94. package/dist/commands/workflow/branches.js +64 -10
  95. package/dist/commands/workflow/repo.js +14 -2
  96. package/dist/commands/workflow/workflows.js +4 -3
  97. package/dist/install/hosts.js +11 -4
  98. package/dist/shared/bkit-latest.js +150 -0
  99. package/dist/shared/timeouts.js +6 -0
  100. package/package.json +1 -1
@@ -1,4 +1,4 @@
1
- <!-- Note: Reports live at `docs/audits/{YYYYMM}/{slug}.md`. `{YYYYMM}` = UTC month of this run. `{slug}` = template basename without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Never overwrite. `@bkit-audit-generate` fills this template. -->
1
+ <!-- Note: Reports live at `docs/audits/{YYYYMM}/{slug}.md`. `{YYYYMM}` = UTC month of this run. `{slug}` = template basename without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Never overwrite. The report is stamped with a `bkit:anchor` block recording the audited commit (`baseSha`) and branch (`baseRef`); never hand-author or edit it. `@bkit-audit-generate` fills this template. -->
2
2
 
3
3
  <!-- bkit:start -->
4
4
 
@@ -81,10 +81,13 @@ Fixes land on call sites a sweep already knew; the doc records the rule. A later
81
81
 
82
82
  **Checkpoint:** Check off all core items. Check conditional items only when applicable. Each item: available → tool and version; missing → fallback, gap in `Not Checked`, fix in `Process Improvements`. Unnamed gap reads as passed. never abort for a missing capability.
83
83
 
84
+ **Credentials:** probe direnv before marking a token / env var missing: `direnv exec . sh -c '[ -n "${VAR}" ] && echo set || echo unset'`; `unset` = missing. Run credentialed CLIs as `direnv exec . <cmd>`. No direnv (cloud session) → plain env check. Report names, never values.
85
+
84
86
  #### Core
85
87
 
86
88
  Always verify.
87
89
 
90
+ - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
88
91
  - [ ] **Text Search:** Steps 2, 5–14, 17, 19 — literals, env names, routes, workflows, e.g. `git grep`, ripgrep. Fallback: none; name gap. Literal searched as regex matching nothing reads as clean — name tool and whether pattern was literal.
89
92
  - [ ] **Call Graph:** Steps 5, 9 — who calls a guard, e.g. language server `find_referencing_symbols`, `tsserver`. Fallback: text search only; empty = inconclusive, not absence.
90
93
  - [ ] **Live Read:** Steps 7, 11, 22 — one read-only GET per web origin; DNS for mail auth; `security.txt` fetch. Fallback: committed config only; served headers, DNS, `security.txt` → `Not Checked`.
@@ -112,7 +115,7 @@ Verify only when applicable.
112
115
 
113
116
  ### Probe Steps
114
117
 
115
- - [ ] **Step 1 — Previous Run:** Record `git rev-parse HEAD`. Read newest prior report for this slug under `docs/audits/`. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
118
+ - [ ] **Step 1 — Previous Run:** Audited commit = this report's `bkit:anchor` `baseSha`. Read newest prior report for this slug under `docs/audits/`; its commit = its `bkit:anchor` `baseSha`, else the HEAD its `Previous Run` recorded. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
116
119
  - [ ] **Step 2 — Classes:** Before any new pass, re-grep all previously swept classes. Signatures = prior report class list + `Project Instructions`. Each: literal signature, owner file if any, hits outside owner. Clean class = result — record it. Env var read (e.g. `process.env.X`, `os.environ[...]`) and never declared = control never executed; reachability → `bkit-audit-dead-code`. Patterns literal, never regex. Literal class = candidate CI guard → propose under `Process Improvements`; do not add this run. **Done when:** `Classes` row per class: signature · hits outside owner · clean or finding.
117
120
  - [ ] **Step 3 — Threat Model:** Read threat model. STRIDE (or model method) per boundary: web, native, machine clients, inbound mail, webhooks, background jobs, privileged service credentials. Diff vs shipped since previous report commit. Uncovered boundary = finding; propose update, do not edit doc. No threat model = first finding. **Done when:** `Threat Model` lists every boundary: covered / finding.
118
121
  - [ ] **Step 4 — Pass:** Broad pass all current Top 10 categories and ASVS chapters before targeted steps; use project application-security checklist or skill if present. Targeted steps = proof; this pass catches categories no later step names. **Done when:** each category in `Checked` as checked (name later step) / finding / `none`.
@@ -128,14 +131,14 @@ Verify only when applicable.
128
131
  - [ ] **Step 14 — Secrets:** Nothing staged that should not be (env files, credentials, tokens, keys); check git history + tree. Remote secrets via sanctioned env sync path, never direct CLI — other path = finding. Documented rotation cadence → verify followed; cadence nobody executes = dead-control shape. Declared-unused vs used-undeclared: latter = dead control (`bkit-audit-dead-code`); former = unnecessary secret. Public build prefixes (e.g. `NEXT_PUBLIC_*`, `EXPO_PUBLIC_*`, `VITE_*`) + client bundle: no server-only keys (service-role, secret key, etc.). Name location; never copy value. **Done when:** `Secrets` lists every public-prefixed name and history hit, values omitted.
129
132
  - [ ] **Step 15 — Access:** Secrets + production-reachable accounts/tokens. Per platform (source host, app host, database, payments, model provider, email, jobs, error tracker, mobile build, store): access holders and roles; 2FA enforced?; long-lived tokens (PAT, deploy keys, service accounts) with scope and last use. Unnamed account, unused token, or excess admin = finding. No-expiry token → recorded reason. Name account and role, never token. Record store signing key holders (distribution cert, upload key). **Done when:** `Access` row per platform: roles · 2FA · tokens · verdict, or `Not Checked`.
130
133
  - [ ] **Step 16 — Deploy:** Production: no browser source maps (delete after error tracker upload); no framework stack traces. Production secrets not in preview/dev (any branch may build preview, where host builds them). Preview deploys (if any) behind deployment protection (`bkit-audit-config` records; confirm here). No test-only routes/helpers (seeding, live-test support, demo-tenant) in production builds. Server DB connections require TLS. **Done when:** each item met / finding / not applicable (why), in `Checked`.
131
- - [ ] **Step 17 — Supply:** Run package-manager audit; disposition output. Audit command absent from all CI lanes = finding. Vuln-alert PRs bypassing freshness delay → confirm land, not queue. CI actions pinned to commit SHA, not floating tag; no new unpinned actions; record clean result. Each workflow/job declares narrowest token permissions; none → repo default; list declarations and over-wide scopes. `pull_request_target` (untrusted PR + target secrets) = finding. PR title, branch name, or comment body in shell step = finding. Secret echo or arg-printing command → log leak despite masking: check secret steps for trace/debug/verbose CI. Install scripts: every allow-list entry since previous report + build justification. Frozen lockfile everywhere. New dependencies since previous report: real package name, not lookalike. Deployed framework versions vs advisories (e.g. middleware-bypass header, server-component RCE). Authorisation never relies on middleware alone. Open audit findings vs recorded remediation timeframes per severity; none recorded → propose. Package-manager audit misses native managers (CocoaPods, Gradle, SwiftPM) — check separately. Export SBOM (dependency-graph, CycloneDX, SPDX) for audited commit + each release; link from `Supply` for next diff. Published artifact → build provenance (e.g. SLSA Build L2 attestations). CI workflow change → explicit human confirmation; report, do not edit. Missing updater config → `bkit-audit-dependencies` (Bot Health); do not re-derive here. **Done when:** `Supply` holds audit disposition, permission table, SBOM link, each finding.
134
+ - [ ] **Step 17 — Supply:** Run package-manager audit; disposition output. Audit command absent from all CI lanes = finding. Allow-list rows (e.g. `scripts/ci/accepted-advisories.json`): reason still true, expiry within timeframe; renewed despite a patched release = finding. Vuln-alert PRs bypassing freshness delay → confirm land, not queue. CI actions pinned to commit SHA, not floating tag; no new unpinned actions; record clean result. Each workflow/job declares narrowest token permissions; none → repo default; list declarations and over-wide scopes. `pull_request_target` (untrusted PR + target secrets) = finding. PR title, branch name, or comment body in shell step = finding. Secret echo or arg-printing command → log leak despite masking: check secret steps for trace/debug/verbose CI. Install scripts: every allow-list entry since previous report + build justification. Frozen lockfile everywhere. New dependencies since previous report: real package name, not lookalike. Deployed framework versions vs advisories (e.g. middleware-bypass header, server-component RCE). Authorisation never relies on middleware alone. Open audit findings vs recorded remediation timeframes per severity; none recorded → propose. Package-manager audit misses native managers (CocoaPods, Gradle, SwiftPM) — check separately. Export SBOM (dependency-graph, CycloneDX, SPDX) for audited commit + each release; link from `Supply` for next diff. Published artifact → build provenance (e.g. SLSA Build L2 attestations). CI workflow change → explicit human confirmation; report, do not edit. Missing updater config → `bkit-audit-dependencies` (Bot Health); do not re-derive here. **Done when:** `Supply` holds audit disposition, permission table, SBOM link, each finding.
132
135
  - [ ] **Step 18 — Repository:** Secret scanning + push protection on? Private repo may need paid host product. Without it: history scanner in pre-commit + CI. Custom pattern for machine-token prefix. Dependency alerts on; default CI token read-only (`bkit-audit-config` too); CI create/approve PRs off. Release + integration rulesets: required review, required checks, no force-push/deletion, owner review for workflow + migration files. `bkit-audit-config` = rulesets vs CI job names; this step = what they protect. `bkit-audit-repo` = code owners; if none, what enforces review. Each sweep: scorecard + workflow linter (report-only); disposition (credential persistence, cache poisoning, template injection, excessive permissions, beyond Step 17). Deploy creds: OIDC or short-lived tokens where supported; production secrets behind environment protection. **Done when:** `Repository` row per setting: expected · actual · verdict.
133
136
  - [ ] **Step 19 — Data:** Never log raw personal data — new log call sites too. SDK defaults = logging: error-tracker PII capture, bodies, breadcrumbs, scrub hook; job-runner payloads/outputs; host request logs. Processors: zero-retention claims, machine-client hosts, additions since last run — new processor = finding until documented. Contract, region, lawful basis → `bkit-audit-privacy`. API: over-broad routes; error envelopes leaking internals. Deletion beyond table trace vs documented retention: embeddings, file objects, raw inbound, processor copies — table trace → `bkit-audit-privacy`; name cross-post. **Done when:** `Data` row per log sink and processor: what can land · verdict.
134
137
  - [ ] **Step 20 — Events:** Inventory security events; each logged with actor, tenant, route, outcome, no secrets: auth failures, authz denials, token issue/revoke, role/membership changes, rate-limit trips, webhook-signature failures, mail-auth drops. Each class alerts a person. Prove delivery via existing non-prod test hook without config change; no hook → alert delivery `Not Checked`. Unalerted log = absent. Failure-mode map → `bkit-audit-reliability`; this list = security events. Fail closed: per control, record dependency failure behavior (cache timeout, auth outage, billing, model error, missing env) — must fail closed or alert. Null guard fix: throw or error-log at construction when required env lacks dependency. Step 2 = env-name signature only. **Done when:** `Events` row per class: logged · alerted · fail closed · verdict.
135
138
  - [ ] **Step 21 — Native:** Native app: session tokens in secure store (Keychain, Keystore), not prefs. No tokens/PII in device logs, backups, sensitive-screen screenshots. Auth callbacks/deep links: verified universal/app links, not claimable custom scheme; deep-link params = untrusted input. Association files served/valid → `bkit-audit-config`. No cleartext exception. OTA code signing on, or record plan lacks it. **Done when:** `Native` row per control group, or skip with evidence no native app.
136
139
  - [ ] **Step 22 — Disclosure:** Published vuln disclosure policy; `/.well-known/security.txt` with monitored `Contact`, unexpired `Expires` (RFC 9116). Current security incident runbook: paging, Step 15 key revocation, session revoke, breach-notification duties per jurisdiction. General incident → `bkit-audit-reliability`; notification timelines → `bkit-audit-privacy`. Last tested restore date from newest `bkit-audit-database` report. **Done when:** each requirement met or finding, in `Checked`.
137
140
  - [ ] **Step 23 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: row per ASVS chapter, Top 10 category, API Security Top 10 risk, (native app) MASVS group → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. Project security checklist/skill covers current releases; lag → name which. **Done when:** no empty row.
138
- - [ ] **Step 24 — Anything Else:** (a) Security-touching changes since previous commit (routes, server actions, machine-client tools, webhooks, processors, workflows, env vars, platforms, outbound hosts, native features) → one-line verdict each vs Step 23 chapter list. (b) ~30 min bounded pass: senior appsec flags no step asks; since previous run read incidents, `bkit-audit-logs`, new `docs/failures.jsonl`, vendor status — what would no step catch? **Done when:** `Beyond the Steps` holds both passes, or `none`. Class seen on 2 runs → propose step in `Process Improvements`; literal signature class → Step 2 row instead. `Expected` on each finding: destination + safer fix. This run does not file, append ledger, or edit doc: security hole → plan from report; discovered bug → `docs/failures.jsonl` row to append later; storage-policy gap (Step 9) → also `bkit-audit-database`; deletion gap (Step 19) → also `bkit-audit-privacy`; prompt-injection model half (Step 10) → `bkit-audit-llm`, not re-derived; live hostile check → `bkit-audit-red-team`; uncovered trust boundary (Step 3) → proposed doc update, not applied; workflow change (Step 17) → human confirmation, never edit workflow; new literal class → proposed Step 2 row under `Process Improvements`.
141
+ - [ ] **Step 24 — Anything Else:** (a) Security-touching changes since previous commit (routes, server actions, machine-client tools, webhooks, processors, workflows, env vars, platforms, outbound hosts, native features) → one-line verdict each vs Step 23 chapter list. (b) ~30 min bounded pass: senior appsec flags no step asks; since previous run read incidents, `bkit-audit-logs`, new `docs/failures.jsonl`, vendor status — what would no step catch? **Done when:** `Beyond the Steps` holds both passes, or `none`. Class seen on 2 runs → propose step in `Process Improvements`; literal signature class → Step 2 row instead. `Expected` on each finding: destination + safer fix. This run does not file or edit doc; the audit agent writes `docs/failures.jsonl` rows: security hole → plan from report; discovered bug → `docs/failures.jsonl` row; storage-policy gap (Step 9) → also `bkit-audit-database`; deletion gap (Step 19) → also `bkit-audit-privacy`; prompt-injection model half (Step 10) → `bkit-audit-llm`, not re-derived; live hostile check → `bkit-audit-red-team`; uncovered trust boundary (Step 3) → proposed doc update, not applied; workflow change (Step 17) → human confirmation, never edit workflow; new literal class → proposed Step 2 row under `Process Improvements`.
139
142
 
140
143
  ### 🔒 Gate 2: Probes Check
141
144
 
@@ -252,6 +255,13 @@ PENDING
252
255
 
253
256
  PENDING
254
257
 
258
+ ### Suggested Issues
259
+
260
+ <!-- prettier-ignore -->
261
+ | # | Title | Findings | Severity | Next Step | Reason |
262
+ | --- | --- | --- | --- | --- | --- |
263
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
264
+
255
265
  ### Process Improvements
256
266
 
257
267
  PENDING
@@ -265,6 +275,7 @@ PENDING
265
275
  - [ ] **Classes:** every standing class has a row, including the clean ones.
266
276
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
267
277
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
278
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
268
279
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
269
280
 
270
281
  > `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.
@@ -1,4 +1,4 @@
1
- <!-- Note: Reports live at `docs/audits/{YYYYMM}/{slug}.md`. `{YYYYMM}` = UTC month of this run. `{slug}` = template basename without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Never overwrite. `@bkit-audit-generate` fills this template. -->
1
+ <!-- Note: Reports live at `docs/audits/{YYYYMM}/{slug}.md`. `{YYYYMM}` = UTC month of this run. `{slug}` = template basename without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Never overwrite. The report is stamped with a `bkit:anchor` block recording the audited commit (`baseSha`) and branch (`baseRef`); never hand-author or edit it. `@bkit-audit-generate` fills this template. -->
2
2
 
3
3
  <!-- bkit:start -->
4
4
 
@@ -76,10 +76,13 @@ Each suppression made sense in one PR; nothing re-reads them. Glob hiding one de
76
76
 
77
77
  **Checkpoint:** Check off all core items. Check conditional items only when applicable. Each item: available → tool and version; missing → fallback, gap in `Not Checked`, fix in `Process Improvements`. Unnamed gap reads as passed. never abort for a missing capability.
78
78
 
79
+ **Credentials:** probe direnv before marking a token / env var missing: `direnv exec . sh -c '[ -n "${VAR}" ] && echo set || echo unset'`; `unset` = missing. Run credentialed CLIs as `direnv exec . <cmd>`. No direnv (cloud session) → plain env check. Report names, never values.
80
+
79
81
  #### Core
80
82
 
81
83
  Always verify.
82
84
 
85
+ - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
83
86
  - [ ] **Scanner:** Steps 2–4 — pinned in manifest, e.g. `slop-scan`. Fallback: skip scanner steps; run code / config steps.
84
87
  - [ ] **Worktree:** Steps 2–8 — detached worktree off default branch. Fallback: Steps 5–7 read-only in main checkout; Steps 3, 8 `Not Checked`.
85
88
  - [ ] **Git History:** Steps 5, 8 — full history for blame and churn. Fallback: ages and churn `Not Checked`.
@@ -102,7 +105,7 @@ Verify only when applicable.
102
105
 
103
106
  ### Probe Steps
104
107
 
105
- - [ ] **Step 1 — Previous Run:** Record `git rev-parse HEAD`. Read newest prior report for this slug under `docs/audits/`. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
108
+ - [ ] **Step 1 — Previous Run:** Audited commit = this report's `bkit:anchor` `baseSha`. Read newest prior report for this slug under `docs/audits/`; its commit = its `bkit:anchor` `baseSha`, else the HEAD its `Previous Run` recorded. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
106
109
  - [ ] **Step 2 — Isolate:** Find scanner run (package scripts). Detached worktree off default branch (no new branch); clean `git status` before start; removed before report finishes. **Done when:** worktree path and clean status in `Checked`, or absent scanner recorded.
107
110
  - [ ] **Step 3 — Hidden Findings:** Pinned scanner, committed config → JSON baseline. Stripped config (build-artifact ignores only, no overrides, all rules on) under restore guard → scan → restore → `diff` byte-identical. Suppressed = in stripped, not baseline; stripped count not fix-list. Count override blocks. Restore fails → STOP; restore committed config; record finding. **Done when:** baseline / stripped / suppressed / override-block counts in `Counts`; config diff empty.
108
111
  - [ ] **Step 4 — Verdicts:** Read each suppressed site, not rule name → verdict. `DELETE` needs reference check: language-server references where available + text search basename (script / config refs language server lacks). Text search over-reports, language server under-reports → agreement = signal. Re-run every empty result once before `DELETE`. **Done when:** every suppressed finding has verdict and evidence.
@@ -178,6 +181,13 @@ PENDING
178
181
 
179
182
  PENDING
180
183
 
184
+ ### Suggested Issues
185
+
186
+ <!-- prettier-ignore -->
187
+ | # | Title | Findings | Severity | Next Step | Reason |
188
+ | --- | --- | --- | --- | --- | --- |
189
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
190
+
181
191
  ### Process Improvements
182
192
 
183
193
  PENDING
@@ -191,6 +201,7 @@ PENDING
191
201
  - [ ] **Series:** `Counts` beside previous report's counts, or marked baseline.
192
202
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
193
203
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
204
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
194
205
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
195
206
 
196
207
  > `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.
@@ -1,4 +1,4 @@
1
- <!-- Note: Reports live at `docs/audits/{YYYYMM}/{slug}.md`. `{YYYYMM}` = UTC month of this run. `{slug}` = template basename without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Never overwrite. `@bkit-audit-generate` fills this template. -->
1
+ <!-- Note: Reports live at `docs/audits/{YYYYMM}/{slug}.md`. `{YYYYMM}` = UTC month of this run. `{slug}` = template basename without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Never overwrite. The report is stamped with a `bkit:anchor` block recording the audited commit (`baseSha`) and branch (`baseRef`); never hand-author or edit it. `@bkit-audit-generate` fills this template. -->
2
2
 
3
3
  <!-- bkit:start -->
4
4
 
@@ -72,10 +72,13 @@ Green suite = tests passed — not that they could fail, that every promise has
72
72
 
73
73
  **Checkpoint:** Check off all core items. Check conditional items only when applicable. Each item: available → tool and version; missing → fallback, gap in `Not Checked`, fix in `Process Improvements`. Unnamed gap reads as passed. never abort for a missing capability.
74
74
 
75
+ **Credentials:** probe direnv before marking a token / env var missing: `direnv exec . sh -c '[ -n "${VAR}" ] && echo set || echo unset'`; `unset` = missing. Run credentialed CLIs as `direnv exec . <cmd>`. No direnv (cloud session) → plain env check. Report names, never values.
76
+
75
77
  #### Core
76
78
 
77
79
  Always verify.
78
80
 
81
+ - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
79
82
  - [ ] **Git:** Steps 1, 14 — `git rev-parse`, diff since previous report. Fallback: run marked baseline; ages and the what-changed pass `Not Checked`.
80
83
  - [ ] **Test Runner:** Steps 3, 6, 9, 10 — execute or read reports, e.g. Vitest, Jest, pytest. Fallback: static read only; counts, mutation, clock runs `Not Checked`.
81
84
  - [ ] **Web:** Step 13 — fetch anchor standards. Fallback: versions recorded as unread.
@@ -99,7 +102,7 @@ Verify only when applicable.
99
102
 
100
103
  ### Probe Steps
101
104
 
102
- - [ ] **Step 1 — Previous Run:** Record `git rev-parse HEAD`. Read newest prior report for this slug under `docs/audits/`. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
105
+ - [ ] **Step 1 — Previous Run:** Audited commit = this report's `bkit:anchor` `baseSha`. Read newest prior report for this slug under `docs/audits/`; its commit = its `bkit:anchor` `baseSha`, else the HEAD its `Previous Run` recorded. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
103
106
  - [ ] **Step 2 — Scope:** Every product area for Steps 3–5 (behaviour usually crosses packages). Every package or app for Steps 6–11. Area shared with native client → every platform; one defect can have a different cause on each. **Done when:** every area, every package, platforms in `Scope`; tools and commands in `Checked`.
104
107
  - [ ] **Step 3 — Behaviours:** Start from product should-do, not code — code finds untested code, not promises with no test or unguarded failures. Rows from:
105
108
  - Screens and routes (each action one row; finishing separate from opening).
@@ -149,7 +152,7 @@ Verify only when applicable.
149
152
  - [ ] **Step 9 — Runs:** Every test file has a lane. Names putting file outside every run (see Step 6). Suites skipping when setup fails instead of failing. Skips (e.g. `test.skip`, `fixme`, `describe.skip`, `pytest.mark.skip`), env-dependent skips. Stale build output runner now collects (e.g. Vitest 4 and later does not ignore `dist/` by default). The 20 slowest tests per tier from runner reports. Slow test = next one someone skips. **Done when:** rows in `Runs`.
150
153
  - [ ] **Step 10 — Time:** Date/calendar/timezone logic → unit tests with `TZ` non-UTC zone observing DST (e.g. `Pacific/Auckland`, `America/St_Johns`) on process before workers spawn. Then date-touching suites with clock pinned near month end and DST change (e.g. `vi.setSystemTime`, Playwright `page.clock`), throwaway setup removed after. Record tests whose result changes. List suites never pinning clock. **Done when:** results in `Time`, or skip with evidence.
151
154
  - [ ] **Step 11 — Copies:** Same test procedure in several places (open dialog, create user, read credentials). Disagreeing copies first. Agreeing copies need single owner only if likely to drift. One owner created → next step adds guard failing on new copy. Code graph finds copied functions; copied statement sequences need syntax-tree scan. Product-code duplication → `bkit-audit-duplication`. **Done when:** groups in `Copies`, or `none`.
152
- - [ ] **Step 12 — Route:** No finding without re-checkable evidence: `file:line`, or query, run id, measurement, plus tool. Language-server empty inconclusive → corroborate text search. Report names where each finding goes; sending is next step. App bug → `docs/failures.jsonl` row and issue; security bugs flagged for project security milestone. Missing test small → test to write. Missing test large → follow-up issue. Cannot-fail test → fix, positive control (break code, watch red, restore), `docs/failures.jsonl` row. Behaviour no recorded intent → question for maintainer; do not guess from code. Tier too high → lower-tier test to write; higher-tier stays until new one seen red. Equivalent mutant → disable comment to add. Timezone/date result → app bug if app wrong; else test fix and `docs/failures.jsonl` row. Flaky → `bkit-audit-flakes`. Coverage floor move → `bkit-audit-coverage`. Check as CI gate → `bkit-audit-gates`. Dead code → `bkit-audit-dead-code`. **Done when:** every finding's Expected names destination.
155
+ - [ ] **Step 12 — Route:** No finding without re-checkable evidence: `file:line`, or query, run id, measurement, plus tool. Language-server empty inconclusive → corroborate text search. Report names where each finding goes; sending is next step; the audit agent writes `docs/failures.jsonl` rows. App bug → `docs/failures.jsonl` row and issue; security bugs flagged for project security milestone. Missing test small → test to write. Missing test large → follow-up issue. Cannot-fail test → fix, positive control (break code, watch red, restore), `docs/failures.jsonl` row. Behaviour no recorded intent → question for maintainer; do not guess from code. Tier too high → lower-tier test to write; higher-tier stays until new one seen red. Equivalent mutant → disable comment to add. Timezone/date result → app bug if app wrong; else test fix and `docs/failures.jsonl` row. Flaky → `bkit-audit-flakes`. Coverage floor move → `bkit-audit-coverage`. Check as CI gate → `bkit-audit-gates`. Dead code → `bkit-audit-dead-code`. **Done when:** every finding's Expected names destination.
153
156
  - [ ] **Step 13 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per OWASP API Security Top 10 item and ASVS chapter (attack rows Step 3), per test-smell in catalogue (shapes Step 7) → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. Do not change steps during run. **Done when:** no empty row.
154
157
  - [ ] **Step 14 — Anything Else:** (a) Everything since previous report commit touching suite (test files/helpers, fixtures/factories, unit/browser/device runner config, CI test lanes, routes/workers/migrations/external services tests cover) → one-line verdict each. (b) Bounded ~30 min pass: senior test engineer flags outside steps; read since previous run (incidents, `bkit-audit-logs`, new `docs/failures.jsonl`, vendor status) — what would no step catch? **Done when:** `Beyond the Steps` holds both passes, or `none`. Class seen on 2 runs → propose step in `Process Improvements`.
155
158
 
@@ -248,6 +251,13 @@ PENDING
248
251
 
249
252
  PENDING
250
253
 
254
+ ### Suggested Issues
255
+
256
+ <!-- prettier-ignore -->
257
+ | # | Title | Findings | Severity | Next Step | Reason |
258
+ | --- | --- | --- | --- | --- | --- |
259
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
260
+
251
261
  ### Process Improvements
252
262
 
253
263
  PENDING
@@ -261,6 +271,7 @@ PENDING
261
271
  - [ ] **Series:** test count and runtime per tier, and both scores, beside previous report's numbers, or marked baseline.
262
272
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
263
273
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
274
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
264
275
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
265
276
 
266
277
  > `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.
@@ -1,4 +1,4 @@
1
- <!-- Note: Reports live at `docs/audits/{YYYYMM}/{slug}.md`. `{YYYYMM}` = UTC month of this run. `{slug}` = template basename without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Never overwrite. `@bkit-audit-generate` fills this template. -->
1
+ <!-- Note: Reports live at `docs/audits/{YYYYMM}/{slug}.md`. `{YYYYMM}` = UTC month of this run. `{slug}` = template basename without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Never overwrite. The report is stamped with a `bkit:anchor` block recording the audited commit (`baseSha`) and branch (`baseRef`); never hand-author or edit it. `@bkit-audit-generate` fills this template. -->
2
2
 
3
3
  <!-- bkit:start -->
4
4
 
@@ -72,10 +72,13 @@ Automated checks never look at a screen. They pass when a title is centred on on
72
72
 
73
73
  **Checkpoint:** Check off all core items. Check conditional items only when applicable. Each item: available → tool and version; missing → fallback, gap in `Not Checked`, fix in `Process Improvements`. Unnamed gap reads as passed. never abort for a missing capability.
74
74
 
75
+ **Credentials:** probe direnv before marking a token / env var missing: `direnv exec . sh -c '[ -n "${VAR}" ] && echo set || echo unset'`; `unset` = missing. Run credentialed CLIs as `direnv exec . <cmd>`. No direnv (cloud session) → plain env check. Report names, never values.
76
+
75
77
  #### Core
76
78
 
77
79
  Always verify.
78
80
 
81
+ - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
79
82
  - [ ] **Screens:** Steps 2, 7–14 — open product (local or existing preview). Fallback: drawings and source only; live claims = hypotheses.
80
83
  - [ ] **Drawings:** Steps 5, 7, 9 — reference drawings readable. Fallback: live vs live only; drawing comparison `Not Checked`.
81
84
  - [ ] **Web:** Step 15 — fetch anchor standards. Fallback: versions recorded as unread.
@@ -99,7 +102,7 @@ Verify only when applicable.
99
102
 
100
103
  ### Probe Steps
101
104
 
102
- - [ ] **Step 1 — Previous Run:** Record `git rev-parse HEAD`. Read newest prior report for this slug under `docs/audits/`. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
105
+ - [ ] **Step 1 — Previous Run:** Audited commit = this report's `bkit:anchor` `baseSha`. Read newest prior report for this slug under `docs/audits/`; its commit = its `bkit:anchor` `baseSha`, else the HEAD its `Previous Run` recorded. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
103
106
  - [ ] **Step 2 — Signals:** Since previous report: funnel drop-off on core flows, support tickets, store-review themes, in-app feedback. Top 5 complaints → each a finding or explained by run end. No users yet → `no users yet`. Missing or untrustworthy funnel data stays listed; fix → `bkit-audit-analytics`. **Done when:** `Signals` holds the five, or `no users yet`.
104
107
  - [ ] **Step 3 — Capture:** Project has a screenshot-capture pipeline (`Project Instructions` names it, incl. how a run opts in, e.g. commit-message marker) → use finished run with artifact still inside retention window. No pipeline or no such run → hand walk; capture `Not Checked`. Record run id, event type, opt-in markers. Fetch and review before artifact expires. **Done when:** run id in `Capture`, or absence recorded.
105
108
  - [ ] **Step 4 — Manifest:** Download that run's report artifact. Read manifest and gap step in same job's log, where the pipeline emits them: every route and test id the run did not reach → this run's blind spot. **Done when:** manifest path in `Capture` and gap list in `Gaps`, or skip recorded.
@@ -215,6 +218,13 @@ PENDING
215
218
 
216
219
  PENDING
217
220
 
221
+ ### Suggested Issues
222
+
223
+ <!-- prettier-ignore -->
224
+ | # | Title | Findings | Severity | Next Step | Reason |
225
+ | --- | --- | --- | --- | --- | --- |
226
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
227
+
218
228
  ### Process Improvements
219
229
 
220
230
  PENDING
@@ -228,6 +238,7 @@ PENDING
228
238
  - [ ] **Series:** every series beside previous report's numbers, or marked baseline.
229
239
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
230
240
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
241
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
231
242
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
232
243
 
233
244
  > `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.
@@ -1,4 +1,4 @@
1
- <!-- Note: Plans live at `docs/plans/{YYYYMM}/{FID}-plan.md` (canonical month bucket). `{YYYYMM}` = creation month, set once by the first workflow run for `{FID}`. Logs sit at `docs/plans/{YYYYMM}/logs/{FID}/` and are delete-eligible. The canonical copy is also stamped with a `bkit:anchor` block recording its base commit; never hand-author or edit it. `@bkit-plan-generate` fills this template. -->
1
+ <!-- Note: Plans live at `docs/plans/{YYYYMM}/{FID}-plan.md` (canonical month bucket). `{YYYYMM}` = creation month, set once by the first workflow run for `{FID}`. Logs sit at `docs/plans/{YYYYMM}/logs/{FID}/` and are delete-eligible. The canonical copy is stamped with a `bkit:anchor` block recording the base commit (`baseSha`), its ref (`baseRef`), and the design it targets (`designPath`, `designBaseSha`); never hand-author or edit it. `@bkit-plan-generate` fills this template. -->
2
2
 
3
3
  <!-- bkit:start -->
4
4
 
@@ -329,6 +329,16 @@ export const SETUP_TIPS: readonly SetupTip[] = [
329
329
  steps: "`.bkit/templates.md` § Prettier tables.",
330
330
  fires: (cwd) => !exists(cwd, "scripts/prettier/bkit-insert-ignore.mjs"),
331
331
  },
332
+ {
333
+ id: "tmp-prune",
334
+ title: "Clear out old scratch files",
335
+ line: "Scratch files agents leave in tmp/ are never cleared, so the folder keeps growing. Add the clean-up that runs when you push.",
336
+ why: "Agents leave logs and scratch files in tmp/ on every run. Each push deletes the ones untouched for a week, so the folder stays small without anyone thinking about it.",
337
+ ask: "Copy .bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs to scripts/cleanup/, then copy the `tmp/ prune` block from .bkit/templates/.husky/pre-push into .husky/pre-push above the gates.",
338
+ steps: "`.bkit/templates.md` § tmp/ prune.",
339
+ fires: (cwd) =>
340
+ exists(cwd, ".husky/pre-push") && !exists(cwd, "scripts/cleanup/bkit-tmp-prune.mjs"),
341
+ },
332
342
 
333
343
  // --- setup: only some setups -----------------------------------------------------------
334
344
  {
@@ -2,16 +2,15 @@
2
2
  // dry-run mode (commands/install/install.ts runInstall); this file holds the installed-module
3
3
  // detection that scopes its drift gate and the drift verdict.
4
4
 
5
- import * as fs from "node:fs";
6
- import * as path from "node:path";
7
5
  import type { ModuleFlag } from "../../cli.js";
6
+ import { detectInstalledHostModules } from "../../install/hosts.js";
8
7
  import type { PreflightFinding } from "../../checks/before/index.js";
9
8
  import { type MissingOwnedHook, describeMissingOwnedHook } from "../../checks/after/managed.js";
10
9
  import { LOG_PREFIX } from "../../shared/log-prefix.js";
11
10
 
12
11
  /**
13
12
  * Installed-module set, detected by sentinel-file presence. Always core, plus the installed
14
- * subset of {claude, cursor, opencode, codex}. Two callers:
13
+ * hosts (detectInstalledHostModules). Two callers:
15
14
  * - `bkit check` — scopes the drift gate, so a `--cursor`-only repo does not
16
15
  * report `.claude/**` as drift.
17
16
  * - `bkit upgrade` — scopes the template walk, so upgrade does NOT force-create files for a
@@ -25,14 +24,7 @@ import { LOG_PREFIX } from "../../shared/log-prefix.js";
25
24
  * Dependency-updater files are not modules: bkit never drift-checks them.
26
25
  */
27
26
  export function detectInstalledModules(cwd: string): Set<ModuleFlag> {
28
- const mods = new Set<ModuleFlag>(["core"]);
29
- if (fs.existsSync(path.join(cwd, ".claude", "agents"))) mods.add("claude");
30
- if (fs.existsSync(path.join(cwd, ".cursor", "agents"))) mods.add("cursor");
31
- if (fs.existsSync(path.join(cwd, ".opencode", "agents"))) mods.add("opencode");
32
- if (fs.existsSync(path.join(cwd, ".codex", "agents"))) mods.add("codex");
33
- if (fs.existsSync(path.join(cwd, ".agents", "plugins", "bkit", "plugin.json")))
34
- mods.add("antigravity");
35
- return mods;
27
+ return new Set<ModuleFlag>(["core", ...detectInstalledHostModules(cwd)]);
36
28
  }
37
29
 
38
30
  // Check mode: exit-1 on drift (totalWrites > 0). runInstall emits the banner first.
@@ -21,6 +21,7 @@ import {
21
21
  import type { SuppressionNote } from "../../checks/after/suppression.js";
22
22
  import { collectTips } from "../../checks/tips/index.js";
23
23
  import { parseDotenv } from "../../install/cloud-env.js";
24
+ import { detectInstalledHostModules } from "../../install/hosts.js";
24
25
 
25
26
  /**
26
27
  * `bkit status` — read-only host/provider status.
@@ -99,9 +100,7 @@ export function runStatus(cwd: string, logPrefix: string): void {
99
100
  const codexPresent = fs.existsSync(codexDir);
100
101
 
101
102
  // --- antigravity host ---
102
- const antigravityPresent = fs.existsSync(
103
- path.join(cwd, ".agents", "plugins", "bkit", "plugin.json"),
104
- );
103
+ const antigravityPresent = detectInstalledHostModules(cwd).has("antigravity");
105
104
 
106
105
  const opencodeStatus = opencodePresent
107
106
  ? `INSTALLED (${providerLabel}: ${opencodeProviderDisplay} / model: ${opencodeModel})`
@@ -30,7 +30,9 @@ import {
30
30
  type ManifestEntry,
31
31
  type ModuleName,
32
32
  type IssueTracker,
33
+ ISSUE_TRACKERS,
33
34
  } from "../../install/manifest.js";
35
+ import { OPENCODE_PROVIDERS } from "../../shared/egress.js";
34
36
  import {
35
37
  isConsumerModified,
36
38
  mergeCanonicalHashes,
@@ -120,33 +122,42 @@ export interface UninstallResult {
120
122
  // ---------------------------------------------------------------------------
121
123
 
122
124
  /**
123
- * Detect the tracker bkit seeded into opencode.json from its mcp keys. The template ships an
124
- * `@@OPENCODE_TRACKER_MCP@@` sentinel KEY that renders to `github` / `linear` at install, so a
125
- * strip-scope keyed on the raw template never matches — these detectors let uninstall render the
126
- * template the same way the install did before stripping. Keyed on bkit's known tracker names so
127
- * a consumer-added mcp server is never mistaken for bkit's.
125
+ * Strip bkit's scope from `.opencode/opencode.json`. The template ships `@@OPENCODE_*@@`
126
+ * sentinel KEYS that render to the consumer's tracker and provider, and install keeps every
127
+ * earlier provider block and tracker entry (install is additive), so one file can hold several.
128
+ * Render the template once per known tracker and once per supported provider, then remove each
129
+ * `mcp` entry and `provider` block identical to a rendered one; an entry the consumer added or
130
+ * edited stays whole. The rest of the template (permission sandbox, plugin list) strips leaf by
131
+ * leaf like any Tier-2 JSON file. Reads only the template.
128
132
  */
129
- function detectOpencodeTracker(doc: Record<string, JsonValue>): IssueTracker {
130
- const mcp = doc.mcp;
131
- if (mcp !== null && typeof mcp === "object" && !Array.isArray(mcp)) {
132
- if ("github" in mcp) return "github";
133
- if ("linear" in mcp) return "linear";
133
+ export function stripOpencodeJsonScope(
134
+ consumer: Record<string, JsonValue>,
135
+ templatePath: string,
136
+ cwd: string,
137
+ ): Record<string, JsonValue> {
138
+ const render = (tracker: IssueTracker, provider: string): Record<string, JsonValue> =>
139
+ JSON.parse(renderOpencodeJson(templatePath, tracker, provider, cwd)) as Record<
140
+ string,
141
+ JsonValue
142
+ >;
143
+ const ownedMcp: Record<string, JsonValue> = {};
144
+ for (const tracker of ISSUE_TRACKERS) {
145
+ const { mcp } = render(tracker, OPENCODE_PROVIDERS[0]);
146
+ if (isJsonObject(mcp)) Object.assign(ownedMcp, mcp);
134
147
  }
135
- return "none";
136
- }
137
-
138
- /** Detect the opencode provider key bkit seeded (the first `provider` block key). */
139
- function detectOpencodeProvider(doc: Record<string, JsonValue>): string {
140
- const provider = doc.provider;
141
- if (provider !== null && typeof provider === "object" && !Array.isArray(provider)) {
142
- const keys = Object.keys(provider);
143
- if (keys.length > 0) {
144
- const first = keys[0];
145
- // Zen block is keyed `opencode` (built-in id); map back to the bkit CLI key.
146
- return first === "opencode" ? "opencode-zen" : first;
147
- }
148
+ const ownedProviders: Record<string, JsonValue> = {};
149
+ for (const provider of OPENCODE_PROVIDERS) {
150
+ const rendered = render("none", provider).provider;
151
+ if (isJsonObject(rendered)) Object.assign(ownedProviders, rendered);
148
152
  }
149
- return "opencode-zen";
153
+ const rest = render("none", OPENCODE_PROVIDERS[0]);
154
+ delete rest.mcp;
155
+ delete rest.provider;
156
+
157
+ const out = JSON.parse(JSON.stringify(consumer)) as Record<string, JsonValue>;
158
+ removeOwnedEntries(out, "mcp", ownedMcp);
159
+ removeOwnedEntries(out, "provider", ownedProviders);
160
+ return stripTier2JsonScope(out, rest);
150
161
  }
151
162
 
152
163
  export function stripTier2JsonScope(
@@ -219,16 +230,28 @@ export function stripMcpTrackerEntries(
219
230
  template: Record<string, JsonValue>,
220
231
  ): Record<string, JsonValue> {
221
232
  const out = JSON.parse(JSON.stringify(consumer)) as Record<string, JsonValue>;
222
- const servers = out.mcpServers;
223
233
  const owned = template.mcpServers;
224
- if (!isJsonObject(servers) || !isJsonObject(owned)) return out;
225
- for (const [key, entry] of Object.entries(owned)) {
226
- if (JSON.stringify(servers[key]) === JSON.stringify(entry)) delete servers[key];
227
- }
228
- if (Object.keys(servers).length === 0) delete out.mcpServers;
234
+ if (isJsonObject(owned)) removeOwnedEntries(out, "mcpServers", owned);
229
235
  return out;
230
236
  }
231
237
 
238
+ /**
239
+ * Delete each entry of `doc[key]` identical to the same-named entry in `owned`, then drop
240
+ * `doc[key]` once empty. Entries that differ, and names `owned` lacks, stay. Mutates `doc`.
241
+ */
242
+ function removeOwnedEntries(
243
+ doc: Record<string, JsonValue>,
244
+ key: string,
245
+ owned: Record<string, JsonValue>,
246
+ ): void {
247
+ const entries = doc[key];
248
+ if (!isJsonObject(entries)) return;
249
+ for (const [name, entry] of Object.entries(owned)) {
250
+ if (JSON.stringify(entries[name]) === JSON.stringify(entry)) delete entries[name];
251
+ }
252
+ if (Object.keys(entries).length === 0) delete doc[key];
253
+ }
254
+
232
255
  function isJsonObject(v: JsonValue | undefined): v is Record<string, JsonValue> {
233
256
  return v !== null && typeof v === "object" && !Array.isArray(v);
234
257
  }
@@ -582,19 +605,10 @@ export async function runUninstall(
582
605
  }
583
606
  const raw = fs.readFileSync(absPath, "utf-8");
584
607
  const consumerDoc = JSON.parse(raw) as Record<string, JsonValue>;
585
- let templateRaw = fs.readFileSync(templatePath, "utf-8");
586
- // opencode.json ships `@@OPENCODE_*@@` sentinel KEYS that render to the consumer's
587
- // tracker / provider at install; strip-scope keyed on the RAW template never matches
588
- // the rendered keys, so bkit's mcp + provider blocks (a token-referencing config)
589
- // survive a full uninstall. Render the template with the consumer's OWN tracker +
590
- // provider first so the keys line up and the bkit-owned scope strips cleanly.
591
- if (templateRaw.includes("@@OPENCODE_TRACKER_MCP@@")) {
592
- templateRaw = renderOpencodeJson(
593
- templatePath,
594
- detectOpencodeTracker(consumerDoc),
595
- detectOpencodeProvider(consumerDoc),
596
- );
597
- }
608
+ const templateRaw = fs.readFileSync(templatePath, "utf-8");
609
+ // opencode.json ships `@@OPENCODE_*@@` sentinel KEYS; stripOpencodeJsonScope
610
+ // renders them for every tracker and provider bkit can have written.
611
+ const isOpencodeJson = templateRaw.includes("@@OPENCODE_TRACKER_MCP@@");
598
612
  const templateDoc = JSON.parse(templateRaw) as Record<string, JsonValue>;
599
613
  // `.claude/settings.json` is not written verbatim: after rendering the
600
614
  // template, install appends one `WebFetch(domain:<d>)` grant per entry in
@@ -620,7 +634,9 @@ export async function runUninstall(
620
634
  }
621
635
  const stripped = MCP_JSON_RELPATHS.has(summary.file)
622
636
  ? stripMcpTrackerEntries(consumerDoc, templateDoc)
623
- : stripTier2JsonScope(consumerDoc, templateDoc);
637
+ : isOpencodeJson
638
+ ? stripOpencodeJsonScope(consumerDoc, templatePath, ctx.cwd)
639
+ : stripTier2JsonScope(consumerDoc, templateDoc);
624
640
  const strippedJson = JSON.stringify(stripped, null, 2) + "\n";
625
641
  if (Object.keys(stripped).length === 0) {
626
642
  // All keys were bkit-owned → delete file
@@ -49,6 +49,7 @@ import {
49
49
  runUpgradeAdvisories,
50
50
  } from "./install.js";
51
51
  import { setLogPrefix } from "../../shared/log-prefix.js";
52
+ import { BKIT_PACKAGE, lookupLatestPublished } from "../../shared/bkit-latest.js";
52
53
  import {
53
54
  getInstallManifest,
54
55
  getModuleManifest,
@@ -536,18 +537,17 @@ export function updateCanonicalHashesAfterUpgrade(
536
537
  * registry auth). Hard-exits with guidance on failure — the caller has nothing
537
538
  * to fall back to.
538
539
  */
539
- async function resolveLatestPublishedVersion(cwd: string): Promise<string> {
540
- const { spawnSync } = await import("node:child_process");
541
- const r = spawnSync("pnpm", ["view", "@cbartens/bkit", "version"], { cwd, encoding: "utf-8" });
542
- if (r.status !== 0 || !r.stdout || !r.stdout.trim()) {
540
+ function resolveLatestPublishedVersion(cwd: string): string {
541
+ const latest = lookupLatestPublished(cwd, null);
542
+ if (latest === null) {
543
543
  console.error(
544
- `${LOG_PREFIX} could not resolve the latest @cbartens/bkit version from the registry ` +
545
- `(pnpm view exit ${r.status ?? "null"}). Check your network / registry access, ` +
544
+ `${LOG_PREFIX} could not resolve the latest ${BKIT_PACKAGE} version from the registry ` +
545
+ `(pnpm view failed). Check your network / registry access, ` +
546
546
  `or pin a version with --to=<version>.`,
547
547
  );
548
548
  process.exit(1);
549
549
  }
550
- return r.stdout.trim();
550
+ return latest;
551
551
  }
552
552
 
553
553
  /**
@@ -562,9 +562,8 @@ async function resolveLatestPublishedVersion(cwd: string): Promise<string> {
562
562
  */
563
563
  export async function runSelfBump(flags: UpgradeFlags, cwd: string): Promise<boolean> {
564
564
  const installed = getInstallingVersion();
565
- // --latest needs async registry resolution, but planSelfBump's injected resolver
566
- // is sync; resolve the latest first (only when asked), then feed it a constant.
567
- const latestVersion = flags.latest ? await resolveLatestPublishedVersion(cwd) : "";
565
+ // Resolve the latest first (only when asked), then feed planSelfBump a constant.
566
+ const latestVersion = flags.latest ? resolveLatestPublishedVersion(cwd) : "";
568
567
  const resolvedPlan = planSelfBump(
569
568
  installed,
570
569
  { toVersion: flags.toVersion, latest: flags.latest },
@@ -962,7 +961,8 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
962
961
 
963
962
  // Network allowlist + MCP allows — OpenCode from renderOpencodeJson; Claude enrich
964
963
  // below; Cursor `.cursor/allowlist.json` + `.cursor/cli.json` only when cursor
965
- // module installed.
964
+ // module installed. Written artifacts get their canonicalHashes refreshed below.
965
+ const artifactWrites: string[] = [];
966
966
  {
967
967
  const cwd = process.cwd();
968
968
  if (renderModules.has("cursor")) {
@@ -971,6 +971,7 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
971
971
  writeCursorCliPermissionsArtifact(cwd, upgradeFlags.dryRun),
972
972
  ]) {
973
973
  if (art.wrote) {
974
+ artifactWrites.push(art.path);
974
975
  console.log(
975
976
  `${LOG_PREFIX}${upgradeFlags.dryRun ? " [dry-run]" : ""} upgrade: ${art.path}`,
976
977
  );
@@ -1015,6 +1016,7 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
1015
1016
  ...result.updated,
1016
1017
  ...renderedDocPaths,
1017
1018
  ...mcpWs.writes.map((w) => path.relative(process.cwd(), w.path)),
1019
+ ...artifactWrites,
1018
1020
  ],
1019
1021
  skipped: result.skipped,
1020
1022
  skippedSeedable: result.skippedSeedable,