@cbartens/bkit 5.2.2 → 5.2.3

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 (82) hide show
  1. package/.bkit/README.md +1 -1
  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/comparison.md +114 -45
  5. package/.bkit/core/.bkit/install.md +3 -3
  6. package/.bkit/core/.bkit/jsonl.md +3 -3
  7. package/.bkit/core/.bkit/prompts.md +6 -5
  8. package/.bkit/core/.bkit/providers.md +5 -4
  9. package/.bkit/core/.bkit/templates.md +11 -10
  10. package/.bkit/core/.bkit/workflows.md +7 -5
  11. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +5 -1
  12. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -2
  13. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +5 -2
  14. package/.bkit/core/docs/templates/bkit-audit-adoption.md +5 -2
  15. package/.bkit/core/docs/templates/bkit-audit-agents.md +5 -2
  16. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +5 -2
  17. package/.bkit/core/docs/templates/bkit-audit-analytics.md +5 -2
  18. package/.bkit/core/docs/templates/bkit-audit-annotations.md +6 -3
  19. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +5 -2
  20. package/.bkit/core/docs/templates/bkit-audit-app-store.md +5 -2
  21. package/.bkit/core/docs/templates/bkit-audit-architecture.md +5 -2
  22. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +5 -2
  23. package/.bkit/core/docs/templates/bkit-audit-config.md +5 -2
  24. package/.bkit/core/docs/templates/bkit-audit-cost.md +5 -2
  25. package/.bkit/core/docs/templates/bkit-audit-coverage.md +5 -2
  26. package/.bkit/core/docs/templates/bkit-audit-database.md +5 -2
  27. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -2
  28. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +5 -2
  29. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +5 -2
  30. package/.bkit/core/docs/templates/bkit-audit-documentation.md +5 -2
  31. package/.bkit/core/docs/templates/bkit-audit-duplication.md +5 -2
  32. package/.bkit/core/docs/templates/bkit-audit-failures.md +6 -3
  33. package/.bkit/core/docs/templates/bkit-audit-flakes.md +6 -3
  34. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  35. package/.bkit/core/docs/templates/bkit-audit-issues.md +5 -2
  36. package/.bkit/core/docs/templates/bkit-audit-llm.md +5 -2
  37. package/.bkit/core/docs/templates/bkit-audit-logs.md +16 -12
  38. package/.bkit/core/docs/templates/bkit-audit-models.md +5 -2
  39. package/.bkit/core/docs/templates/bkit-audit-privacy.md +5 -2
  40. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -2
  41. package/.bkit/core/docs/templates/bkit-audit-red-team.md +5 -2
  42. package/.bkit/core/docs/templates/bkit-audit-reliability.md +6 -3
  43. package/.bkit/core/docs/templates/bkit-audit-repo.md +5 -2
  44. package/.bkit/core/docs/templates/bkit-audit-security.md +6 -3
  45. package/.bkit/core/docs/templates/bkit-audit-slop.md +5 -2
  46. package/.bkit/core/docs/templates/bkit-audit-testing.md +5 -2
  47. package/.bkit/core/docs/templates/bkit-audit-usability.md +5 -2
  48. package/.bkit/core/docs/templates/bkit-plan.md +1 -1
  49. package/.bkit/core/engine/commands/install/check.ts +3 -11
  50. package/.bkit/core/engine/commands/install/doctor.ts +2 -3
  51. package/.bkit/core/engine/commands/install/uninstall.ts +60 -44
  52. package/.bkit/core/engine/commands/install/upgrade.ts +4 -1
  53. package/.bkit/core/engine/commands/workflow/branches.ts +13 -4
  54. package/.bkit/core/engine/install/hosts.ts +14 -4
  55. package/.bkit/core/engine/ledgers/telemetry.ts +3 -4
  56. package/.bkit/core/hooks/guardrails-read.js +4 -9
  57. package/.bkit/core/hooks/guardrails-tiers.js +312 -28
  58. package/.bkit/core/prompts/bkit-audit-generate.md +19 -5
  59. package/.bkit/shared/.claude/settings.json +19 -0
  60. package/.bkit/shared/.opencode/opencode.json +21 -1
  61. package/.bkit/shared/docs/deployments.md +14 -0
  62. package/.bkit/templates/.github/workflows/bkit-ci.yml +9 -0
  63. package/.bkit/templates/context/bkit-cloudrun.md +28 -19
  64. package/.bkit/templates/context/bkit-expo.md +30 -13
  65. package/.bkit/templates/context/bkit-inngest.md +54 -17
  66. package/.bkit/templates/context/bkit-resend.md +36 -8
  67. package/.bkit/templates/context/bkit-sentry.md +11 -4
  68. package/.bkit/templates/context/bkit-stripe.md +39 -22
  69. package/.bkit/templates/context/bkit-supabase.md +45 -20
  70. package/.bkit/templates/context/bkit-vercel.md +45 -16
  71. package/.bkit/templates/scripts/ci/accepted-advisories.json +7 -0
  72. package/.bkit/templates/scripts/ci/check-dependency-audit.mjs +200 -0
  73. package/.bkit/templates/scripts/ci/check-dependency-audit.test.mjs +127 -0
  74. package/CHANGELOG.md +39 -0
  75. package/README.md +76 -20
  76. package/dist/commands/install/check.js +3 -15
  77. package/dist/commands/install/doctor.js +2 -1
  78. package/dist/commands/install/uninstall.js +52 -45
  79. package/dist/commands/install/upgrade.js +4 -1
  80. package/dist/commands/workflow/branches.js +13 -5
  81. package/dist/install/hosts.js +11 -4
  82. 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
 
@@ -79,10 +79,13 @@ One per probe, on the `Probes` row.
79
79
 
80
80
  **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.
81
81
 
82
+ **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.
83
+
82
84
  #### Core
83
85
 
84
86
  Always verify.
85
87
 
88
+ - [ ] **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 → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`. never retry or reword a blocked call to get past it.
86
89
  - [ ] **Target:** Steps 2–12 — non-production deployment of this commit, resolved by commit SHA, confirmed serving. Fallback: none. Probes stay `INCONCLUSIVE`. NEVER point them at production.
87
90
  - [ ] **Identities:** Steps 2, 5–12, 14 — create and delete synthetic users and tenants, guarded so a non-synthetic identity cannot be deleted. Fallback: none. Do not probe with real accounts.
88
91
  - [ ] **Web:** Steps 2, 13 — each platform's penetration-testing page, and anchor standards. Fallback: policy unread → do not send probes; record why.
@@ -106,7 +109,7 @@ Verify only when applicable.
106
109
 
107
110
  ### Probe Steps
108
111
 
109
- - [ ] **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.
112
+ - [ ] **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.
110
113
  - [ ] **Step 2 — Engage:** Record commit and non-production URL deployed for it (the deployment the live lane resolves for that SHA, not a branch alias that may be stale). Confirm serving. Write scope in `Scope`. **In:** non-production web URL (e.g. preview deploy, staging), API host, machine-client endpoint, inbound mail domain, data API via client public key, background-job serve endpoint, native build if tested. **Out:** production, release branch, persistent demo tenant, every third party's own platform, anything not on in-list. Read current penetration-testing page of each platform probes touch (app host, database, native vendor if in scope). Record what they allow and plan tier. Page forbids probe → do not send; `INCONCLUSIVE`. Create two synthetic tenants, attacker, and victim, each with roles the product distinguishes. Issue machine-client token for each owner where product has one, on plan the feature allows. Seed victim with few records, one recurring record, attachment. Do not touch persistent demo tenant. Read newest `bkit-audit-security` and `bkit-audit-llm` reports. Every finding they could not prove → probe; model audit's prompt-only rules → probe. Every trust boundary threat model names → ≥1 probe. No threat model → say so in `Scope`. Before destructive probe, confirm no other live test holds target database. Record window. Do not wait for named approver. Later probe degrades target, touches non-synthetic data, or reaches third party → stop remaining probes; record stop in `Scope`. **Done when:** `Scope` holds URL, commit, in-list, out-list, platform rules, plan tier, identities (no tokens), suspicion list. **Probe row** (every later probe): request with tokens redacted, response status, relevant body, verdict. `BROKE` adds blast radius by reasoning, not pivoting.
111
114
  - [ ] **Step 3 — Surface:** List attack surface at this commit: routes, server actions, machine-client tools, webhooks, response headers of each in-scope origin. Diff vs previous report's list. Everything new → ≥1 probe. **Done when:** `Surface` holds list and diff.
112
115
  - [ ] **Step 4 — Retest:** Re-run every earlier `BROKE` whose fix landed, from recorded reproduction. `FIXED` or `STILL BROKE`, with fix commit. Confirm regression test prior run named exists; if not → `bkit-audit-testing`. **Done when:** `Retests` row per prior break, or `none`.
@@ -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
 
@@ -71,10 +71,13 @@ Failure paths are least-tested: happy path is tested; vendor outage stays unwalk
71
71
 
72
72
  **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.
73
73
 
74
+ **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.
75
+
74
76
  #### Core
75
77
 
76
78
  Always verify.
77
79
 
80
+ - [ ] **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 → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`. never retry or reword a blocked call to get past it.
78
81
  - [ ] **Code Search:** Steps 2–12, 14, 16 — text search and language server for callers, e.g. ripgrep, Serena, `tsserver`. Language-server hits under-report; empty is inconclusive → corroborate with text search and name the tool. Fallback: text search only; name it per claim.
79
82
  - [ ] **Web:** Step 15 — fetch anchor standards. Fallback: versions recorded as unread.
80
83
 
@@ -83,7 +86,7 @@ Always verify.
83
86
  Verify only when applicable.
84
87
 
85
88
  - [ ] **Metrics:** Hosted traces, errors, or health endpoint → Steps 3, 13 — SLO queries and alert config, e.g. Sentry, Datadog, Better Stack. Fallback: repo config only; live measurements `Not Checked`.
86
- - [ ] **Job Platform:** Background jobs → Steps 6, 7 — flow control and replay docs, read-only, e.g. Inngest, Temporal. Fallback: code only; live run history `Not Checked`.
89
+ - [ ] **Job Platform:** Background jobs → Steps 6, 7 — flow control and replay docs, read-only, e.g. Inngest, Temporal. Log access: `.agents/context.md` `context-fetch` blocks below `bkit:end` are ready-made read-only readers (`bkit context list-blocks` → each block's `context` and `body`); set a body's `# Customise:` knobs to the audit window; run it via `direnv exec . bash`. Fallback: code only; live run history `Not Checked`.
87
90
  - [ ] **Deploy Platform:** Hosted deploys → Step 12 — skew protection, rollout, rollback history, e.g. Vercel API, Cloud Run. Fallback: repo config only; dashboard settings `Not Checked`.
88
91
  - [ ] **Vendor Status:** External dependencies → Step 13 — status feeds. Fallback: none; feeds `Not Checked`.
89
92
 
@@ -96,7 +99,7 @@ Verify only when applicable.
96
99
 
97
100
  ### Probe Steps
98
101
 
99
- - [ ] **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.
102
+ - [ ] **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.
100
103
  - [ ] **Step 2 — Surfaces:** One table, kept run to run for diffs. Outbound calls (every SDK client and every `fetch` host); webhook receivers; background work (job functions and scheduled database jobs); write paths (routes and server actions that change data). Per dependency: hard (journey fails without it) or soft (degrades), and what it depends on in turn. Transitive counts (e.g. auth mail via mail vendor → mail outage is sign-in outage). Surface in code, not docs = finding; doc rewrite → `bkit-audit-documentation`. **Done when:** `Surfaces` lists every surface with hard/soft and transitive deps, or `N/A` and STOP.
101
104
  - [ ] **Step 3 — Journeys:** Every user-reliant journey. Per journey: SLI as good/total ratio, SLO over rolling 28-day window, current measurement with query that produced it. Keep table run to run. No target, or target nobody measures = finding. Error-budget policy: what changes when budget spent (e.g. feature freeze, mandatory postmortem when one incident uses >20% of budget). Record whether policy triggered since previous run and whether obeyed. No policy = finding. **Done when:** `Journeys` row per journey: SLI · SLO · measurement and query · budget triggered · obeyed.
102
105
  - [ ] **Step 4 — Dropped Errors:** Codebase-wide, not only errors that reached a log (`bkit-audit-logs` owns those). `catch` that neither rethrows, returns error, nor logs at `warn` or above; client calls whose error never read (e.g. Supabase `{ error }`, AWS SDK, Prisma); promises without `await` or `.catch`; broad catches turning every failure into one generic message so caller cannot tell timeout from bug. Dropped, never logged = invisible to user and operators; those first. Deliberate best-effort (telemetry, fire-and-forget notification) OK when code says so. Linter-catchable class (e.g. `@typescript-eslint/no-floating-promises`, unread client `error`) → name rule under `Process Improvements`; do not add it. Adding gate → `bkit-audit-gates`. **Done when:** every hit = finding with `file:line`.
@@ -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 @@ Every task leaves a worktree, branch, stash, or scratch directory; nothing's job
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 → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`. never retry or reword a blocked call to get past it.
88
91
  - [ ] **Git:** Steps 2–7, 9 — local checkout, worktrees, branches, stashes. Fallback: none; no checkout → `N/A` and STOP.
89
92
  - [ ] **Host API:** Steps 4, 8 — read-only, e.g. `gh api`. Fallback: local git only; remote branches, pull requests, and settings `Not Checked`.
90
93
  - [ ] **Web:** Step 10 — fetch anchor standards. Fallback: versions recorded as unread.
@@ -107,7 +110,7 @@ Verify only when applicable.
107
110
 
108
111
  ### Probe Steps
109
112
 
110
- - [ ] **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.
113
+ - [ ] **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.
111
114
  - [ ] **Step 2 — Checkout:** Name machine and checkout. Worktrees, stashes, scratch directories are local — fresh cloud checkout sees none; say so, not clean. Remote branches and pull requests are shared; every run checks those. **Done when:** machine, checkout, and which surfaces are local-only in `Checked`.
112
115
  - [ ] **Step 3 — Worktrees:** `git worktree list --porcelain`. Per worktree: branch, ahead/behind integration branch, `git cherry`, pull-request state, uncommitted changes (`git status --porcelain`), last commit date, size (`du -sh`). Locked or files modified in the last day → KEEP or ASK, never REMOVE (agent may still be running). Also `git worktree prune --dry-run` for entries whose directory is gone. Never prune for real. **Done when:** `Worktrees` row per entry with verdict; totals in `Totals`.
113
116
  - [ ] **Step 4 — Branches:** Local: merged by ancestry, merged by squash (pull request merged, or `git cherry` all `-`), upstream gone, agent-prefix branches with no worktree. Remote: branches other than integration, production, dependency-update bot's, with pull-request state. Record delete-on-merge; when off, merged pull request leaves its branch. Unmerged with no pull request: every commit is RESCUE until shown otherwise. Open pull requests with no activity for 30 days, and old drafts. Tags no release or deploy uses. **Done when:** `Branches` row per item with verdict; counts in `Totals`.
@@ -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 → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`. 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,7 +131,7 @@ 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.
@@ -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 → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`. 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.
@@ -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 → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`. 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).
@@ -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 → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`. 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.
@@ -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
 
@@ -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
@@ -962,7 +962,8 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
962
962
 
963
963
  // Network allowlist + MCP allows — OpenCode from renderOpencodeJson; Claude enrich
964
964
  // below; Cursor `.cursor/allowlist.json` + `.cursor/cli.json` only when cursor
965
- // module installed.
965
+ // module installed. Written artifacts get their canonicalHashes refreshed below.
966
+ const artifactWrites: string[] = [];
966
967
  {
967
968
  const cwd = process.cwd();
968
969
  if (renderModules.has("cursor")) {
@@ -971,6 +972,7 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
971
972
  writeCursorCliPermissionsArtifact(cwd, upgradeFlags.dryRun),
972
973
  ]) {
973
974
  if (art.wrote) {
975
+ artifactWrites.push(art.path);
974
976
  console.log(
975
977
  `${LOG_PREFIX}${upgradeFlags.dryRun ? " [dry-run]" : ""} upgrade: ${art.path}`,
976
978
  );
@@ -1015,6 +1017,7 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
1015
1017
  ...result.updated,
1016
1018
  ...renderedDocPaths,
1017
1019
  ...mcpWs.writes.map((w) => path.relative(process.cwd(), w.path)),
1020
+ ...artifactWrites,
1018
1021
  ],
1019
1022
  skipped: result.skipped,
1020
1023
  skippedSeedable: result.skippedSeedable,
@@ -395,8 +395,9 @@ export function stampAnchor(
395
395
  text: string,
396
396
  baseSha: string,
397
397
  design?: { path: string; baseSha: string },
398
+ baseRef: string = UPSTREAM,
398
399
  ): string {
399
- const header = [ANCHOR_OPEN, `baseSha: ${baseSha}`, `baseRef: ${UPSTREAM}`];
400
+ const header = [ANCHOR_OPEN, `baseSha: ${baseSha}`, `baseRef: ${baseRef}`];
400
401
  if (design) header.push(`designPath: ${design.path}`, `designBaseSha: ${design.baseSha}`);
401
402
  header.push(ANCHOR_CLOSE);
402
403
  const body = anchorLines(text)
@@ -1180,6 +1181,7 @@ function anchorStampVerb(ctx: RunContext): number {
1180
1181
  return EXIT_NO_FILE;
1181
1182
  }
1182
1183
  if (baseSha === "") throw new CommandError(EXIT.USAGE, "--base-sha must be non-empty");
1184
+ const baseRef = str(ctx.flags.baseRef) ?? UPSTREAM;
1183
1185
  const designFlag = str(ctx.flags.design);
1184
1186
  const designFile = designFlag === undefined ? undefined : path.resolve(ctx.cwd, designFlag);
1185
1187
  const design =
@@ -1190,7 +1192,7 @@ function anchorStampVerb(ctx: RunContext): number {
1190
1192
  }
1191
1193
  : undefined;
1192
1194
  const before = fs.readFileSync(file, "utf-8");
1193
- const after = stampAnchor(before, baseSha, design);
1195
+ const after = stampAnchor(before, baseSha, design, baseRef);
1194
1196
  // Temp file + rename: a crash mid-write never leaves a half-stamped doc.
1195
1197
  const tmp = `${file}.bkit-anchor.tmp`;
1196
1198
  fs.writeFileSync(tmp, after);
@@ -1198,6 +1200,7 @@ function anchorStampVerb(ctx: RunContext): number {
1198
1200
  ctx.emit({
1199
1201
  file: rel,
1200
1202
  baseSha,
1203
+ baseRef,
1201
1204
  designPath: design?.path ?? null,
1202
1205
  designBaseSha: design?.baseSha ?? null,
1203
1206
  changed: before !== after,
@@ -1452,7 +1455,7 @@ export const branchesCommand: CommandSpec = {
1452
1455
  },
1453
1456
  "anchor-stamp": {
1454
1457
  summary:
1455
- "Put a <!-- bkit:anchor --> block recording the base commit on top of a design/plan doc (idempotent).",
1458
+ "Put a <!-- bkit:anchor --> block recording the base commit on top of a design/plan doc or audit report (idempotent).",
1456
1459
  flags: [
1457
1460
  { name: "file", type: "string", required: true, help: "doc to stamp (must exist)" },
1458
1461
  {
@@ -1461,6 +1464,11 @@ export const branchesCommand: CommandSpec = {
1461
1464
  required: true,
1462
1465
  help: "base commit the doc was written against (non-empty)",
1463
1466
  },
1467
+ {
1468
+ name: "base-ref",
1469
+ type: "string",
1470
+ help: `ref baseSha was taken from (default ${UPSTREAM}; audit reports pass the audited branch)`,
1471
+ },
1464
1472
  {
1465
1473
  name: "design",
1466
1474
  type: "string",
@@ -1470,6 +1478,7 @@ export const branchesCommand: CommandSpec = {
1470
1478
  output: {
1471
1479
  file: "doc stamped",
1472
1480
  baseSha: "base commit stamped",
1481
+ baseRef: "ref stamped",
1473
1482
  designPath: "design path stamped (null when none)",
1474
1483
  designBaseSha:
1475
1484
  "the design doc's baseSha stamped (null when none; empty when it had no anchor)",
@@ -1482,7 +1491,7 @@ export const branchesCommand: CommandSpec = {
1482
1491
  summary:
1483
1492
  "Read a doc's anchor fields; with --against, decide whether anything landed since its baseSha.",
1484
1493
  flags: [
1485
- { name: "file", type: "string", required: true, help: "design/plan doc" },
1494
+ { name: "file", type: "string", required: true, help: "design/plan doc or audit report" },
1486
1495
  {
1487
1496
  name: "field",
1488
1497
  type: "string",
@@ -5,9 +5,19 @@ import * as path from "node:path";
5
5
  import type { ModuleFlag } from "../cli.js";
6
6
 
7
7
  /**
8
- * Detect which host modules a consumer has installed, by the presence of each host's
9
- * source-rendered agents directory. `bkit upgrade` re-renders only these hosts — never
10
- * force-creating an opencode/cursor tree — and setup tips key host-specific advice on them.
8
+ * The Antigravity plugin's bkit-written paths (install/modules/antigravity.ts). Any one
9
+ * present marks the host installed, so deleting a single file (the manifest included) still
10
+ * leaves the host detected and its missing files reported as drift.
11
+ */
12
+ const ANTIGRAVITY_SENTINELS = ["plugin.json", "hooks.json", "agents", "skills", "hooks"].map((p) =>
13
+ path.join(".agents", "plugins", "bkit", p),
14
+ );
15
+
16
+ /**
17
+ * Detect which host modules a consumer has installed: each host's source-rendered agents
18
+ * directory, or for Antigravity any of its plugin files. `bkit upgrade` re-renders only these
19
+ * hosts — never force-creating an opencode/cursor tree — and setup tips key host-specific
20
+ * advice on them.
11
21
  */
12
22
  export function detectInstalledHostModules(cwd: string): Set<ModuleFlag> {
13
23
  const mods = new Set<ModuleFlag>();
@@ -15,7 +25,7 @@ export function detectInstalledHostModules(cwd: string): Set<ModuleFlag> {
15
25
  if (fs.existsSync(path.join(cwd, ".cursor", "agents"))) mods.add("cursor");
16
26
  if (fs.existsSync(path.join(cwd, ".opencode", "agents"))) mods.add("opencode");
17
27
  if (fs.existsSync(path.join(cwd, ".codex", "agents"))) mods.add("codex");
18
- if (fs.existsSync(path.join(cwd, ".agents", "plugins", "bkit", "plugin.json")))
28
+ if (ANTIGRAVITY_SENTINELS.some((rel) => fs.existsSync(path.join(cwd, rel))))
19
29
  mods.add("antigravity");
20
30
  return mods;
21
31
  }