@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
@@ -33,6 +33,7 @@ Adoption order = `bkit tips` order. Sections below: install steps and traps.
33
33
  | graphify | Code map (`docs/capabilities.md`) agents check before building something again. | Agents rediscover structure each run; ripple effects missed. |
34
34
  | Dependabot / Renovate | Small grouped update PRs; pinned Actions; security fixes skip the queue. | Updates pile into one large risky upgrade. |
35
35
  | Prettier tables | One edited cell = one changed row in the diff. | A one-word table edit diffs as the whole table. |
36
+ | tmp/ prune | Each push deletes scratch files agents left in `tmp/` untouched for a week. | `tmp/` keeps growing; old logs and scratch files are never cleared. |
36
37
  | Cursor editor + cloud agent | Format-on-save, recommended extensions, Cursor cloud-agent image. | Cursor edits miss project formatting; no Cursor cloud agent. |
37
38
  | Launchd GUI env | macOS apps opened from the Dock get the same tokens as the terminal. | Dock-launched editors start signed out. |
38
39
 
@@ -42,7 +43,7 @@ Adoption order = `bkit tips` order. Sections below: install steps and traps.
42
43
  | Tool | Copy from | To | Output you commit |
43
44
  | --- | --- | --- | --- |
44
45
  | CI workflow | `.bkit/templates/.github/workflows/bkit-ci.yml` | `.github/workflows/bkit-ci.yml` | that file |
45
- | CI scripts | `.bkit/templates/scripts/ci/` | `scripts/ci/` | the scripts you adopt (`lanes/resolve-push-base.mjs`; `check-accepted-divergences.mjs` + `accepted-divergences.json`) |
46
+ | CI scripts | `.bkit/templates/scripts/ci/` | `scripts/ci/` | the scripts you adopt (`lanes/resolve-push-base.mjs`; `check-accepted-divergences.mjs` + `accepted-divergences.json`; `check-dependency-audit.mjs` + `accepted-advisories.json`) |
46
47
  | Cloud-agent workflow | `.bkit/templates/.github/workflows/bkit-cloud.yml` | `.github/workflows/bkit-cloud.yml` | that file |
47
48
  | Git hooks (Husky) | `.bkit/templates/.husky/pre-commit`, `.bkit/templates/.husky/pre-push` | `.husky/pre-commit`, `.husky/pre-push` | both files |
48
49
  | Prettier ignore list | `.bkit/templates/.prettierignore` | `.prettierignore` | that file |
@@ -59,6 +60,7 @@ Adoption order = `bkit tips` order. Sections below: install steps and traps.
59
60
  | graphify | `.bkit/templates/scripts/graphify/`, `.bkit/templates/.graphifyignore`, `.bkit/templates/docs/capabilities.md` | same paths at the repo root | `docs/capabilities.md` |
60
61
  | Secrets sync | `.bkit/templates/scripts/secrets/` | `scripts/secrets/` | both files; never `bkit-secrets-state.json` |
61
62
  | Prettier tables | `.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs` | `scripts/prettier/` | that file |
63
+ | tmp/ prune | `.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs` | `scripts/cleanup/` | that file |
62
64
  | Context-fetch blocks | `.bkit/templates/context/bkit-<provider>.md` | below `<!-- bkit:end -->` in `.agents/context.md` | the blocks you use |
63
65
  | Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file |
64
66
 
@@ -91,14 +93,14 @@ Placeholders. Copies keep them raw; replace each in your copy:
91
93
  | `playwright.md` | Playwright on GitHub Actions | `e2e` | failing run's report artifact, failing specs first; inlined files, lines and binary paths capped | `GH_TOKEN` / `E2E_ARTIFACT`, `E2E_JOB_RE`, `E2E_MAX_FILES`, `E2E_MAX_LINES`, `E2E_MAX_BIN` | — | `gh` (base tool) |
92
94
  | `maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's log, sliced to the result steps, each slice tail-bounded | `GH_TOKEN` / `MAESTRO_JOB_RE`, `MAESTRO_STEPS`, `MAESTRO_LOG_TAIL` | — | `gh` (base tool) |
93
95
  | `tavily.md` | any | `web` | web search for upstream causes (untrusted output) | `BKIT_TAVILY_API_KEY` / `QUERY` | — | — |
94
- | `sentry.md` | Sentry | `runtime` | unresolved issues seen in a window (organization issues endpoint), optional environment; trace / window recipes | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST`, `SENTRY_SINCE`, `SENTRY_ENV`, `SENTRY_N` | `sentry.io` | — |
95
- | `vercel.md` | Vercel | `runtime` | serverless + edge error / fatal logs in a window | `VERCEL_TOKEN` / `VERCEL_SCOPE`, `VERCEL_ENV` | `vercel.com` | `vercel` (yes) |
96
- | `supabase.md` | hosted Supabase | `runtime` | Postgres `ERROR` / `FATAL` / `PANIC` lines | `SUPABASE_ACCESS_TOKEN` / `SUPABASE_PROJECT_ID` | `supabase.com` | — |
97
- | `stripe.md` | Stripe | `runtime` | failure / dispute / refund events, filtered by type and window at the source | `STRIPE_SECRET_KEY` / `STRIPE_N`, `STRIPE_SINCE_S` | `stripe.com` | — |
98
- | `resend.md` | Resend | `runtime` | bounced / complained / failed / delayed sends | `RESEND_API_KEY` / — | `resend.com` | — |
99
- | `inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events in a window | `INNGEST_SIGNING_KEY` / `INNGEST_N`, `SINCE_ISO`, `INNGEST_ENV` | `inngest.com` | — |
100
- | `cloudrun.md` | Google Cloud Run | `runtime` | container errors + memory-limit kills | `GCP_CLIENT_EMAIL`, `GCP_PRIVATE_KEY` (headless) / `GCP_PROJECT_ID`, `GCP_SERVICE` | `googleapis.com`, `google.com` | `gcloud` (yes) |
101
- | `expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: build status + errored-build log lines (capped per build); `e2e`: failed jobs' per-flow exceptions, JUnit (capped), screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR`, `EAS_PLATFORM`, `EAS_PROFILE`, `EAS_LOG_N` (`runtime`); `EAS_WF_FILE`, `EAS_JUNIT_N` (`e2e`) | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
96
+ | `sentry.md` | Sentry | `runtime` | unresolved issues seen in a window (organization issues endpoint), optional environment; trace / window recipes; detector-header strip | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST`, `SENTRY_SINCE`, `SENTRY_ENV`, `SENTRY_N` | `sentry.io` | — |
97
+ | `vercel.md` | Vercel | `runtime` | serverless + edge error / fatal logs in a window, paged past the CLI's 50-line cap, all branches (`--no-branch`) | `VERCEL_TOKEN` / `VERCEL_SCOPE`, `VERCEL_ENV`, `SINCE`, `UNTIL`, `VERCEL_MAX_PAGES` | `vercel.com` | `vercel` (yes) |
98
+ | `supabase.md` | hosted Supabase | `runtime` | Postgres `ERROR` / `FATAL` / `PANIC` counts per hour, severity, SQLSTATE and role; one call per day of window | `SUPABASE_ACCESS_TOKEN` / `SUPABASE_PROJECT_ID`, `SINCE_ISO`, `UNTIL_ISO` | `supabase.com` | — |
99
+ | `stripe.md` | Stripe | `runtime` | failure / dispute / refund events, filtered by type and window at the source, paged; events whose webhook delivery failed | `STRIPE_SECRET_KEY` / `STRIPE_SINCE_S`, `STRIPE_MAX_PAGES` | `stripe.com` | — |
100
+ | `resend.md` | Resend | `runtime` | bounced / complained / failed / delayed sends, paged back to the window start | `RESEND_API_KEY` / `SINCE_ISO`, `RESEND_MAX_PAGES` | `resend.com` | — |
101
+ | `inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events in a window, paged; error class only, never error text | `INNGEST_SIGNING_KEY` / `INNGEST_ENV` (required with a branch key), `SINCE_ISO`, `UNTIL_ISO`, `INNGEST_N`, `INNGEST_MAX_PAGES` | `inngest.com` | — |
102
+ | `cloudrun.md` | Google Cloud Run | `runtime` | container errors + memory-limit kills; service account only when the gcloud login cannot mint a token | `GCP_CLIENT_EMAIL`, `GCP_PRIVATE_KEY` (headless) / `GCP_PROJECT_ID`, `GCP_SERVICE`, `GCP_FILTER` | `googleapis.com`, `google.com` | `gcloud` (yes) |
103
+ | `expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: newest 50 builds' status + errored-build log lines (capped per build); `e2e`: recent and FAILURE run lists, failed jobs' per-flow exceptions, JUnit (capped), screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR`, `EAS_PLATFORM`, `EAS_PROFILE`, `EAS_N`, `EAS_LOG_N` (`runtime`); `EAS_WF_FILE`, `EAS_WF_N`, `EAS_WF_FAIL_N`, `EAS_JUNIT_N` (`e2e`) | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
102
104
  | `serena.md` | Serena MCP server | — | nothing: provision only, installs `serena` in cloud | — | — | `uv` (yes) |
103
105
 
104
106
  MCP names listed: `sentry` / `Sentry`, `vercel` / `Vercel`, `supabase` / `Supabase`, `inngest`, `serena`. Every tool on a listed server runs without a prompt, writes included — list only servers you trust with that.
@@ -126,7 +128,8 @@ Adopt:
126
128
  3. Set the secret env vars locally (app env via `.envrc`, not `.bkit/.env`) and in each cloud dashboard (`.bkit/cloud.md`).
127
129
  4. `bkit install` → the provision recipes reach `.claude/bkit-cloud.md`'s setup script, the domains reach the cloud allowlist and local fetch permissions, the MCP names reach every host's allow rules.
128
130
 
129
- - Without credentials each block self-skips: `exit 0` plus `[context-fetch:<name>] skipped — …` on stderr. `/bkit-debug` narrates that as not checked, never as clean.
131
+ - No credentials, or an API / auth error → block self-skips: `exit 0` plus `[context-fetch:<name>] skipped — …` on stderr. `/bkit-debug` narrates that as not checked, never as clean. `TRUNCATED` on stdout = page cap or a failed later page stopped the read; raise the block's `*_MAX_PAGES` knob.
132
+ - Runtime and EAS blocks' `# Customise:` suggests a positive control: run once over a window holding a known event; nothing back = reader broken, not clean.
130
133
  - `bkit check` advisories point at these files: `context-fetch-missing`, `context-fetch-context-missing`, `context-fetch-source-not-enabled`, `context-fetch-provision-missing`.
131
134
  - Another backend → author a block in the same shape (rules in the managed block of `.agents/context.md`).
132
135
 
@@ -187,7 +190,7 @@ Post-CI router: CI pass on `feat/**` → `/bkit-ship`, fail → `/bkit-debug`; f
187
190
 
188
191
  ## Git hooks — Husky
189
192
 
190
- `pre-commit` runs `bkit:gate:format`; `pre-push` runs `bkit:gate:static-unit` (`bkit:gate:static` on revert branches / commits), then `bkit check`, plus a CI-suppressing-token guard. Workflows care: they commit and push without `--no-verify`, so a failing hook stops a workflow. Reference: https://typicode.github.io/husky/.
193
+ `pre-commit` runs `bkit:gate:format`; `pre-push` runs `bkit:gate:static-unit` (`bkit:gate:static` on revert branches / commits), then `bkit check`, plus a CI-suppressing-token guard and the `tmp/` prune (§ tmp/ prune). Workflows care: they commit and push without `--no-verify`, so a failing hook stops a workflow. Reference: https://typicode.github.io/husky/.
191
194
 
192
195
  ```bash
193
196
  pnpm add -D husky@^9.1.7 # plus "prepare": "husky" (§ Gate tool scripts)
@@ -500,3 +503,19 @@ Prettier aligns markdown tables with no config toggle; one edited cell re-pads e
500
503
  - Skips tables inside ``` / ~~~ fences and tables already wrapped.
501
504
  - A pipe inside an inline-code span is escaped to `\|` only when that restores the separator's column count; an existing `\|` stays literal.
502
505
  - Exit 1 on damage it cannot repair, with or without `--check`: `truncated-row` (more cells than the separator; GFM drops the overflow) and `unrendered-table` (header ≠ separator count; GFM renders raw text). A bare pipe in cell prose is indistinguishable from a delimiter → escape it as `\|` by hand.
506
+
507
+ ## tmp/ prune — old scratch files
508
+
509
+ Each push deletes scratch files agents left in `tmp/` untouched for a week, then the folders that leaves empty. Node >= 20, no dependencies.
510
+
511
+ ```bash
512
+ mkdir -p scripts/cleanup
513
+ cp .bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs scripts/cleanup/
514
+ ```
515
+
516
+ - Wiring: the `tmp/ prune` block in the `.husky/pre-push` template runs it with `--days=7`, ahead of the gates; skipped while `scripts/cleanup/bkit-tmp-prune.mjs` is absent. Your `.husky/pre-push` lacks the block → paste it above the gates.
517
+ - Not a gate: a failed prune prints a warning; the push goes on.
518
+ - `--days=<n>` (n >= 1, default 7). Exit 0 = swept or no `tmp/`; 1 = an entry could not be removed (each named on stderr); 2 = bad arguments.
519
+ - Scope: `tmp/` at the top of the checkout the cwd sits in; each worktree prunes its own. `tmp/` itself stays.
520
+ - Age = file mtime. Symlinks never followed: a symlinked `tmp/` is skipped; a symlink inside is removed by its own age, target untouched. A folder goes only when empty and either the sweep emptied it or its own mtime is past the cutoff → a folder another process just made stays.
521
+ - Hand run: `node scripts/cleanup/bkit-tmp-prune.mjs`. Files to keep belong outside `tmp/`.
@@ -181,7 +181,7 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
181
181
  | Invoke subagents | ✅ via `@agent-name` (Agent tool) | ❌ leaves only |
182
182
  | Write `status.jsonl` / hold `.lock` | ✅ | ❌ |
183
183
 
184
- **Why:** agent runnable standalone (`@bkit-build-challenge .worktrees/xxx-123` without live tracker issue). Inputs via filesystem paths from orchestrator. Outputs on disk: `docs/plans/{YYYYMM}/logs/{FID}/`, plan/design doc, source, or `docs/{knowledge,decisions,deferrals,failures}.jsonl`, `.bkit/issues.jsonl`. Workflow reads agent outputs → decides tracker mirror.
184
+ **Why:** agent runnable standalone (`@bkit-build-challenge-1 .worktrees/xxx-123` without live tracker issue). Inputs via filesystem paths from orchestrator. Outputs on disk: `docs/plans/{YYYYMM}/logs/{FID}/`, plan/design doc, source, or `docs/{knowledge,decisions,deferrals,failures}.jsonl`, `.bkit/issues.jsonl`. Workflow reads agent outputs → decides tracker mirror.
185
185
 
186
186
  ## Common Workflow Anatomy
187
187
 
@@ -602,10 +602,14 @@ baseRef: origin/dev
602
602
 
603
603
  Plan docs add 2 fields, read from the design doc's own anchor: `designPath` (design this plan targets), `designBaseSha` (that doc's own `baseSha`).
604
604
 
605
+ Every stamp (design, plan, sub-plan, audit report) adds 2 more when `.bkit/version` exists: `bkitVersion` (its `pinnedVersion`) and `bkitLatest` (newest published release, empty when unknown; lookup per § Invocation). `bkitVersion` older → the stamp also writes one visible line under the block: `> **Outdated bkit:** generated with bkit X while Y was out … <!-- bkit:outdated -->`. Tool-owned like the block: every re-stamp drops it, rewrites it only while still outdated. Neither line is a capital-letter `Key:` line, so `readHeader` ignores both.
606
+
605
607
  **Orchestrator-owned:** generate subagents have no `Bash` → can't compute a SHA. Orchestrator records `baseSha` at Step 2 (`bkit worktrees setup` → `bkit runtime row --base-sha=` → `runtime-resolved.baseSha`), reads it back at Close Workflow (`bkit runtime assert`) and stamps the canonical with `bkit branches anchor-stamp` (idempotent; plan adds `--design=`); `bkit branches anchor-read` reads it. Hand-written block from either subagent → stripped, replaced, never trusted.
606
608
 
607
609
  **May be empty:** `baseSha` empty = `merge-base` unresolvable, not a failure. `designPath`/`designBaseSha` empty = no design, or design predates this mechanism. Pre-change docs carry no block — `bkit branches anchor-read` returns null fields, not an error.
608
610
 
611
+ **Audit reports** (`docs/audits/{YYYYMM}/{slug}*.md`) carry the same block: `baseSha` = `git rev-parse HEAD` when the report stub is created, `baseRef` = the audited branch (`--base-ref=`), no design fields. Audits have no orchestrator, so `@bkit-audit-generate` runs `bkit branches anchor-stamp` itself right after creating the stub; the block is still tool-written, never hand-written. The next run of the same template reads it as the previous report's commit (each template's Step 1). Reports without a block fall back to the HEAD their `Previous Run` recorded.
612
+
609
613
  **Truth, not intent:** stale `origin/dev` at fetch → recorded `baseSha` is the stale base actually branched from; later diff surfaces that honestly rather than papering over it.
610
614
 
611
615
  **Read by build's Plan Current step** (`/bkit-build` Step 4) — the only consumer of `baseSha` on a plan doc. `designPath` / `designBaseSha` are provenance only and have no consumer: once a plan exists it is judged against the codebase, never against its design. Absent or unreachable `baseSha` skips the judgement, never fails it.
@@ -697,6 +701,7 @@ Then assert each Update/Create artifact exists, non-empty. Empty → **Failure P
697
701
  | Dev lock wait budget | 600s | How long a dev critical section waits for the lock before Failure Path with the holder line (`SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S`). Ship's Failure Path and the build / debug dev-side roadmap mirror pass `--deadline=60` and skip their dev ops rather than hard-failing |
698
702
  | Ship CI wait | 1800s / 30s | Step 9 completion poll budget / interval (`SHIP_CI_WAIT_TIMEOUT_S` / `SHIP_POLL_INTERVAL_S`) |
699
703
  | Ship presence probe | 6 x 10s | Step 9 run-at-head probe before any dispatch (`SHIP_PROBE_ATTEMPTS` x `SHIP_PROBE_INTERVAL_S`) |
704
+ | Newest-bkit lookup | 5s / 86400s / 3600s | Registry query limit / answer reuse / failure reuse for the outdated-bkit check (`BKIT_LATEST_LOOKUP_TIMEOUT_S` / `BKIT_LATEST_CACHE_S` / `BKIT_LATEST_RETRY_S`) |
700
705
 
701
706
  `MAX_*` live in `THRESHOLDS` (`commands/workflow/counters.ts`; `bkit counters max`) and are referenced by name in retry checks (`bkit counters route --limit=`) — never a literal `3`. Waits live in `TIMEOUTS` (`.bkit/core/engine/shared/timeouts.ts`).
702
707
 
@@ -1243,9 +1248,9 @@ Without `acceptEdits` / wildcard allow surface, every `Bash`, `Edit`, `Write`, M
1243
1248
  <!-- prettier-ignore -->
1244
1249
  | Bucket | Patterns | Purpose |
1245
1250
  | --- | --- | --- |
1246
- | `allow` | `Bash(*)`, `Skill(*)`, `WebSearch`, `mcp__github__*`, `mcp__claude_ai_Linear__*`, `Bash(git push --force-with-lease:*)`, `Read(./.env.example)`, `Read(./\*\*/.env.example)`, `WebFetch(domain:…)` per host in the network allowlist (apex + `*.` wildcard) | Blanket-allow shell, skills, tracker MCP, scoped web fetch. `deny` is evaluated first, then `allow`, then `ask` — so the `.env.example` and `--force-with-lease` entries are the carve-outs that beat the `ask`/`deny` rows below. Session-conditional: bucket needs workspace trust; `Bash(*)` dropped in auto mode (§ Cloud sessions). |
1247
- | `ask` | `sudo:*`, `brew install:*`, `(pnpm / npm / bun) publish:*`, `git reset --hard:*`, `git clean -fd(x):*`, `git filter-branch:*`, `git checkout -- .:*`, `git restore .:*`, `git stash drop:*`, `git rebase -i:*`, `gh repo delete:*`, `gh pr close:*`, `gh release delete:*`, `Read(./.env)`, `Read(./.env.\*)`, `Read(./\*\*/.env)`, `Read(./\*\*/.env.\*)`, `Read(./.bkit/.env)` | Per-call human confirmation for destructive ops and secret reads. The `.env` rows are globs, not an enumeration of known filenames — an enumeration silently drops `.env.ci` / `.env.preview` / anything a consumer invents into `defaultMode`. The recursive `./**/` forms cover monorepo `apps/*` and `packages/*`. |
1248
- | `deny` | `Bash(rm -rf /\* | ~/\* | $HOME/\*)`, `Bash(chmod -R 777 /:*)`, `Bash(git push --force)`, `Bash(git push --force \*)`, `Bash(git push -f)`, `Bash(git push -f \*)`, `Read(./\*\*/\*.pem)`, `Read(./\*\*/\*.p12)`, `Read(./\*\*/id_rsa)` | Hard-block catastrophic deletes, force-push and private-key reads. The force-push rows are split into exact + trailing-arg forms rather than the `--force:*` prefix idiom, because a prefix match also swallows `--force-with-lease` and would deny the allowed form. |
1251
+ | `allow` | `Bash(*)`, `Skill(*)`, `WebSearch`, `mcp__github__*`, `mcp__claude_ai_Linear__*`, `Bash(git push --force-with-lease:*)`, `Read(./.env.example)`, `Read(./\*\*/.env.example)`, `WebFetch(domain:…)` per host in the network allowlist (apex + `*.` wildcard) | Blanket-allow shell, skills, tracker MCP, scoped web fetch. Claude evaluates `deny`, then `ask`, then `allow`: an `allow` row never overrides a matching `ask` or `deny`. `--force-with-lease` passes because no `deny` row matches it, not because of its `allow` row; the `.env.example` rows never fire, since `Read(./.env.*)` asks first. Session-conditional: bucket needs workspace trust; `Bash(*)` dropped in auto mode (§ Cloud sessions). |
1252
+ | `ask` | `sudo:*`, `brew install:*`, `(pnpm / npm / bun) publish:*`, `gh repo delete:*`, `gh pr close:*`, `gh release delete:*`; git: `git reset --hard:*`, `git reset \*--hard\*`, `git clean -fd(x):*`, `git clean -\*f\*`, `git filter-branch:*`, `git checkout -- .:*`, `git checkout \*.`, `git checkout \* . \*`, `git restore .:*`, `git restore \*.`, `git restore \* . \*`, `git stash drop:*`, `git rebase -i:*`, `git rebase \* -i( \*)`, `git rebase \*--interactive\*`, `git \* --no-verify( \*)`, `git commit -n\*`, `git commit \* -n( \*)`; `Read(./.env)`, `Read(./.env.\*)`, `Read(./\*\*/.env)`, `Read(./\*\*/.env.\*)`, `Read(./.bkit/.env)` | Per-call human confirmation for destructive ops, hook-skipping commits / pushes and secret reads. The `\*` globs catch the same git commands with flags in another order (`git reset -q --hard`, `git clean -df`); a git global option before the subcommand (`git -C dir reset --hard`) is not matched. The `.env` rows are globs, not an enumeration of known filenames — an enumeration silently drops `.env.ci` / `.env.preview` / anything a consumer invents into `defaultMode`. The recursive `./**/` forms cover monorepo `apps/*` and `packages/*`. Shell reads of secret files (`cat .env`) carry no `Bash(...)` row: a command-text glob cannot tell a read from a mention. |
1253
+ | `deny` | `Bash(rm -rf /\*)`, `Bash(rm -rf ~/\*)`, `Bash(rm -rf $HOME/\*)`, `Bash(chmod -R 777 /:*)`, `Bash(git push --force)`, `Bash(git push --force \*)`, `Bash(git push -f)`, `Bash(git push -f \*)`, `Bash(git push -f\*)`, `Bash(git push \* --force)`, `Bash(git push \* --force \*)`, `Bash(git push \* -f\*)`, `Bash(git push \* +\*)`, `Read(./\*\*/\*.pem)`, `Read(./\*\*/\*.p12)`, `Read(./\*\*/id_rsa)` | Hard-block catastrophic deletes, force-push and private-key reads. Force-push is denied as `--force`, `-f` / an `-f…` cluster, or a `+refspec`, in any argument position. No row is a `--force` prefix: `--force:*` and `--force*` also match `--force-with-lease` and would deny the allowed form. |
1249
1254
 
1250
1255
  Shell `curl` / `wget` are **not** on the Claude `ask` list — they run under `Bash(*)`, with `deny`, the auto-mode classifier, and the advisory `.claude/hooks/bkit-guardrails.cjs` (PreToolUse, matcher `Bash`) as the backstops. Claude rules match a command prefix, not a URL host, so per-domain allows are inexpressible and the only options are blanket-ask or blanket-allow; blanket-ask forces a prompt on **every** shell fetch in **every** mode (a content-scoped `ask` is evaluated before the classifier and beats a matching `allow`), which a cloud session has nobody to answer. `WebFetch(domain:…)` governs the `WebFetch` **tool** only, never `curl` in `Bash`. Cursor gates by parsed URL host (`bkit-guardrails.cjs`), OpenCode via `curl https://{host}/*` allows layered after a `curl *` ask (command-string glob: trailing flags or extra URLs still match, so it narrows rather than blocks). All four run an **allowlisted-host** fetch unprompted; on an **undeclared** host Cursor and OpenCode ask, Claude and Codex emit an advisory instead (Claude to avoid re-adding the prompt, Codex because it cannot prompt).
1251
1256
 
@@ -1294,7 +1299,9 @@ Mechanical step work runs as `bkit <noun> <verb> --flag=value` (also `--flag val
1294
1299
  "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" repo info --fetch
1295
1300
  ```
1296
1301
 
1297
- and holds its `bkit` key as `{BKIT}` (plus `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`); every later block runs `"{BKIT}" <noun> <verb> …`, the orchestrator substituting the path. It is the main checkout's binary, so it works before and without a worktree `node_modules` (adopt mode never installs). The bkit repo links itself as a dev dependency so the same path exists there. A value a later step needs is held from the command's JSON by key (`hold worktreePath as {WORKTREE_PATH}`) — never re-derived by hand; model-held values reach a command as flag values (`--fid={FID}`), never through shell variables. Every command refuses (exit 2) a flag value still carrying a literal `{UPPER}` placeholder — the orchestrator passed it through unsubstituted.
1302
+ and holds its `bkit` key as `{BKIT}` (plus `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`, `bkitAdvisory` as `{BKIT_ADVISORY}`); every later block runs `"{BKIT}" <noun> <verb> …`, the orchestrator substituting the path. It is the main checkout's binary, so it works before and without a worktree `node_modules` (adopt mode never installs). The bkit repo links itself as a dev dependency so the same path exists there. A value a later step needs is held from the command's JSON by key (`hold worktreePath as {WORKTREE_PATH}`) — never re-derived by hand; model-held values reach a command as flag values (`--fid={FID}`), never through shell variables. Every command refuses (exit 2) a flag value still carrying a literal `{UPPER}` placeholder — the orchestrator passed it through unsubstituted.
1303
+
1304
+ **Outdated bkit:** `repo info` also reports `bkitVersion` (`.bkit/version` `pinnedVersion`), `bkitLatest` (newest published `@cbartens/bkit`), `bkitOutdated` (numeric compare; a prerelease is older than its release) and `bkitAdvisory` (one line naming the upgrade command; null unless outdated). Step 1 of every phase workflow emits a non-null `{BKIT_ADVISORY}` as `[bkit-{workflow}] …` and continues — never a stop, never a gate item. Lookup: `pnpm view`, at most once a day; answer cached in `<git common dir>/bkit-latest-version.json` (shared by worktrees, never committed); a failed lookup cached 1 hour. No answer, no pin, or `BKIT_NO_UPDATE_CHECK` set (not `0`) → `bkitLatest` / `bkitOutdated` / `bkitAdvisory` null. Same check stamps every anchored doc (§ Anchor Block).
1298
1305
 
1299
1306
  **Step endings:** a step that writes a `step-done` row ends in one `bkit steps finish` call: it reads each `--agent`'s verdict header from the `--artifact` in the same position (worst verdict wins, `Failures` summed, the prompt's declared header fields required, `Strategy` recorded on the row), derives the attempt (`--attempt=next`, `--attempt-of=<step>:<next|current|count>`; `<attempt>` in a path or message becomes it), runs the gate's mechanical checks before writing, writes the row, commits (`--message`, `<done>` = the log's first `DONE` line), and prints the step's tracker `comment` (`--number` / `--title`). Exit 5 / 6 print `reask` = `{agent, artifact}` for the header-only re-ask. A gate whose step ends in `steps finish` relies on that call's checks; a gate with no finish (Step 1, closes, Step 3 / 9 of ship) runs `bkit steps gate`.
1300
1307
 
@@ -1303,7 +1310,7 @@ and holds its `bkit` key as `{BKIT}` (plus `repoRoot` as `{REPO_ROOT}`, `outboxR
1303
1310
  <!-- prettier-ignore -->
1304
1311
  | Noun | Verbs | Covers |
1305
1312
  | --- | --- | --- |
1306
- | `repo` | `info`, `preflight` | Step 1 owner/repo, branch, behind-`dev` notice, `{BKIT}` / `{REPO_ROOT}` / `{OUTBOX_ROOT}`; advisory dispatch-permission preflight |
1313
+ | `repo` | `info`, `preflight` | Step 1 owner/repo, branch, behind-`dev` notice, outdated-bkit advisory, `{BKIT}` / `{REPO_ROOT}` / `{OUTBOX_ROOT}`; advisory dispatch-permission preflight |
1307
1314
  | `fids` | `check`, `parse`, `find` | FID format asserts; marker / branch FID recovery; the feature already logged for an issue (`find --issue`: exit 0 one, 1 none, 4 several) |
1308
1315
  | `runtime` | `detect`, `row`, `assert` | runtime capability table + `runtime-resolved` row |
1309
1316
  | `locks` | `acquire`, `release` | per-feature `.lock` and `.bkit/.dev.lock` |
@@ -1398,7 +1405,7 @@ Each gate is the previous gate plus its own tier, so the name and the value desc
1398
1405
  | `bkit:gate:static-unit-integration-e2e-live` | not seeded — chains the gate above | debug Step 3 |
1399
1406
  | `bkit:gate:install-static-unit-build` | `pnpm install --frozen-lockfile && pnpm bkit:gate:static-unit && pnpm build` | `@bkit-ship-conflict-resolve` |
1400
1407
 
1401
- Dependency inspection is read-only, not a gate: `bkit:deps:outdated` and `bkit:deps:audit` exist so prompts stop hardcoding `pnpm outdated` / `pnpm audit`.
1408
+ Dependency inspection: `bkit:deps:outdated` / `bkit:deps:audit` exist so prompts stop hardcoding `pnpm outdated` / `pnpm audit`; neither belongs in the table above. CI gate: the copy-and-own `Check Dependency Audit` step (`bkit-tests-static`, `scripts/ci/check-dependency-audit.mjs`) fails on a high / critical advisory without an in-date `scripts/ci/accepted-advisories.json` acceptance (`deployments.md` § Dependency updaters).
1402
1409
 
1403
1410
  `bkit:test:file` is not a gate either: it runs ONE test file — bkit appends the repo-relative path as its argument — and writes a JUnit report to the path in `$BKIT_TEST_REPORT`. `/bkit-build` reads that report for test-first (§ Test-first). Not seeded (no default runs one file on every stack); the `test-file-script-missing` advisory (install, `bkit check`, `bkit upgrade`) hands over the line until it is declared. Call the runner directly: a task runner that caches results or runs dependent packages first breaks the one-file contract.
1404
1411
 
@@ -66,7 +66,11 @@ function decideShell(cmd) {
66
66
  case "ask":
67
67
  // Advisory on this host (Codex cannot prompt).
68
68
  return ask(
69
- `bkit Codex guardrails: this is a destructive or privileged command and Codex cannot prompt for confirmation. It is on the PROHIBITED list in every bkit workflow. Do not run it unless the user asked for this exact command. Note that git clean and git checkout -- . destroy untracked files and uncommitted work, which no reflog can recover. Command: ${c}`,
69
+ `bkit Codex guardrails: this is a destructive or privileged command (${v.what}) and Codex cannot prompt for confirmation. It is on the PROHIBITED list in every bkit workflow. Do not run it unless the user asked for this exact command. Note that git clean and git checkout -- . destroy untracked files and uncommitted work, which no reflog can recover. Command: ${c}`,
70
+ );
71
+ case "secret":
72
+ return ask(
73
+ `bkit Codex guardrails: this command reads ${v.path}, an env/secrets or private-key file, and Codex cannot prompt for confirmation. Do not print secret values; prefer direnv / documented non-secret examples. Command: ${c}`,
70
74
  );
71
75
  case "fetch":
72
76
  return ask(
@@ -3,7 +3,8 @@
3
3
  // Claude `.claude/settings.json` permissions deny/ask and OpenCode permission map).
4
4
  //
5
5
  // Wired from `.cursor/hooks.json`:
6
- // - beforeShellExecution → force-push / recursive-rm / dangerous git+gh
6
+ // - beforeShellExecution → force-push / recursive-rm / dangerous git+gh; shell reads of
7
+ // .env / private-key files ask
7
8
  // - preToolUse (Read|TabRead) → .env ask; private-key deny
8
9
  //
9
10
  // Output: JSON `{ permission: "allow"|"ask"|"deny", user_message?, agent_message? }`
@@ -65,9 +66,14 @@ function decideShell(cmd) {
65
66
  return deny(`Blocked: ${v.what} is denied by bkit Cursor guardrails.`, v.fix);
66
67
  case "ask":
67
68
  return ask(
68
- "bkit Cursor guardrails: confirm this destructive / privileged shell command.",
69
+ `bkit Cursor guardrails: confirm this destructive / privileged shell command (${v.what}).`,
69
70
  `Command requires confirmation: ${c}`,
70
71
  );
72
+ case "secret":
73
+ return ask(
74
+ "bkit Cursor guardrails: confirm a shell read of an env/secrets or private-key file.",
75
+ `Reading ${v.path} through the shell may expose secrets. Prefer direnv / documented non-secret examples. Command: ${c}`,
76
+ );
71
77
  case "fetch":
72
78
  return ask(
73
79
  "bkit Cursor guardrails: confirm outbound curl/wget (host not on network allowlist).",
@@ -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
 
@@ -66,10 +66,13 @@ Target failure: **a gate that stays green while the unchecked surface is where t
66
66
 
67
67
  **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.
68
68
 
69
+ **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.
70
+
69
71
  #### Core
70
72
 
71
73
  Always verify.
72
74
 
75
+ - [ ] **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.
73
76
  - [ ] **Gate Source:** Steps 2, 4, 13 — automated-gate files readable. Fallback: no gate while UI exists = finding; later steps run without snapshot.
74
77
  - [ ] **Checker:** Steps 5, 6 — full rule set, e.g. axe-core, pa11y, Accessibility Insights. Fallback: manual steps only; automated rows `Not Checked`.
75
78
  - [ ] **Web:** Step 15 — fetch anchor standards. Fallback: versions recorded as unread.
@@ -93,7 +96,7 @@ Verify only when applicable.
93
96
 
94
97
  ### Probe Steps
95
98
 
96
- - [ ] **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.
99
+ - [ ] **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.
97
100
  - [ ] **Step 2 — Gate:** Open gate specs and helpers. Record in `Gate`: checker rule set; route list + ready/settle selectors per route; each allowlist; gate-pinned vs audit-run checker version; rules checker changelog adds since previous report version (pinned old version under-reports newer WCAG 2.2 rules). Scope everything below against snapshot. **Done when:** snapshot in `Gate`, or no gate recorded.
98
101
  - [ ] **Step 3 — Laws:** Which laws apply = owner decision; record or unmade (`Project Instructions` names questions). Law requiring public accessibility statement, service info, feedback channel → check they exist. Statement wording vs behaviour → `bkit-audit-privacy`. **Done when:** `Laws` row per regime: applies · why · statement.
99
102
  - [ ] **Step 4 — Allowlists:** Per-offender keys, never runtime hash, never rule downgrade or route exclusion. Honest only if each entry re-read. Per entry: offender still there, reason still true, fixable now? No expiry/owner = permanent exemption = finding. Policy "new entry = finding, not fix" (`Project Instructions`) → new entry = finding. Stale (offender gone, key remains) = finding. **Done when:** `Allowlists` row per entry: still present · reason true · expiry or owner · verdict. Empty → one row `none`, key shape noted.
@@ -250,6 +253,13 @@ PENDING
250
253
 
251
254
  PENDING
252
255
 
256
+ ### Suggested Issues
257
+
258
+ <!-- prettier-ignore -->
259
+ | # | Title | Findings | Severity | Next Step | Reason |
260
+ | --- | --- | --- | --- | --- | --- |
261
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
262
+
253
263
  ### Process Improvements
254
264
 
255
265
  PENDING
@@ -263,6 +273,7 @@ PENDING
263
273
  - [ ] **Sessions:** states the date of the last assistive-technology session and when the next is due.
264
274
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
265
275
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
276
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
266
277
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
267
278
 
268
279
  > `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 @@ bkit ships three folders. Path inside a folder = path it lands at in the repo.
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
  - [ ] **Checkout:** Steps 2–11 — repo with `.bkit/version`. Fallback: none; absent → `N/A` and STOP.
84
87
  - [ ] **Package:** Step 2 — installed package root (e.g. `node_modules/@cbartens/bkit/.bkit/`, resolved via the package manager). Fallback: unpack the pinned version (e.g. `npm pack @cbartens/bkit@<pinnedVersion>` into a throwaway dir); else inventory from `.bkit/templates/` + `canonicalHashes` only, `core/` + `shared/` unwritten files `Not Checked`.
85
88
  - [ ] **bkit CLI:** Steps 4, 5 — `bkit check`, `bkit doctor` (or `pnpm bkit …`). Fallback: hash written files against `canonicalHashes` by hand; advisories `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. Carry each `Adoption` verdict forward with its 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. Carry each `Adoption` verdict forward with its age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
106
109
  - [ ] **Step 2 — Inventory:** List every file in the package's `core/`, `shared/`, `templates/`. Landing path = path inside the folder; `core/engine/`, `core/workflows/`, `core/prompts/` → no landing (workflows + prompts → Step 5 host copies). Join: package file · landing path present · in `canonicalHashes` · repo `.bkit/templates/` copy matches package `templates/`. Kind per file: whole file / managed block / owned keys / template. Findings: `core/` or `shared/` file with landing path absent; `canonicalHashes` entry the package no longer ships; repo `.bkit/templates/` differing from package. Group a folder into one row only when every file shares one verdict. **Done when:** `Inventory` row per shipped file or uniform folder: folder · landing path · kind · present · recorded.
107
110
  - [ ] **Step 3 — Version:** `pinnedVersion` vs installed package vs registry latest; pinned ≠ installed = package bumped without `bkit upgrade`. Behind → release count; release-note changes touching this repo; template paths changed since pinned version. **Done when:** `Version` names all three versions and every relevant release-note change.
108
111
  - [ ] **Step 4 — Check and Doctor:** `bkit check`: exit code, each drift line → cause. `bkit doctor`: each advisory → adopt / reject (why) / not applicable; previous report's reject carried forward, re-raised only when the advisory text changed. **Done when:** `Check and Doctor` row per drift line and advisory.
@@ -201,6 +204,13 @@ PENDING
201
204
 
202
205
  PENDING
203
206
 
207
+ ### Suggested Issues
208
+
209
+ <!-- prettier-ignore -->
210
+ | # | Title | Findings | Severity | Next Step | Reason |
211
+ | --- | --- | --- | --- | --- | --- |
212
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
213
+
204
214
  ### Process Improvements
205
215
 
206
216
  PENDING
@@ -214,6 +224,7 @@ PENDING
214
224
  - [ ] **Series:** `Adoption` diffed against previous report's, or marked baseline.
215
225
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway package unpack removed.
216
226
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
227
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
217
228
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
218
229
 
219
230
  > `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
 
@@ -75,10 +75,13 @@ Each agent host reads its own permissions, hooks, tool servers, model picks; nob
75
75
 
76
76
  **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.
77
77
 
78
+ **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.
79
+
78
80
  #### Core
79
81
 
80
82
  Always verify.
81
83
 
84
+ - [ ] **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.
82
85
  - [ ] **Checkout:** Steps 2–10 — repo-level agent config. Fallback: none; no checkout → `N/A` and STOP.
83
86
  - [ ] **Effective Config:** Steps 2, 4, 6 — host's merged-config view where offered (e.g. `claude mcp list`, a host's permissions or MCP panel). Fallback: files + documented precedence by hand; effective state = hypothesis.
84
87
  - [ ] **Web:** Steps 7, 11 — anchor standards, host references, live model catalogues. Fallback: versions recorded as unread; model pins `Not Checked`.
@@ -100,7 +103,7 @@ Verify only when applicable.
100
103
 
101
104
  ### Probe Steps
102
105
 
103
- - [ ] **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.
106
+ - [ ] **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.
104
107
  - [ ] **Step 2 — Hosts and Layers:** Name machine and checkout. Hosts with repo config or in team use (e.g. Claude Code, Cursor, Codex, opencode). Per host: config file per layer (managed policy, user, repo shared, repo local override, flags / env); documented precedence. Findings: config for unused host; host in use with no repo config; local-override file tracked or not ignored. Fresh cloud checkout: no user / local layer → say so, not clean. **Done when:** `Hosts` row per host × layer: file, present, tracked / ignored, precedence.
105
108
  - [ ] **Step 3 — Instructions:** Per host: instruction files loaded at session start (e.g. `AGENTS.md`, `CLAUDE.md`, always-applied IDE rule files, per-directory files, imports). Findings: host reaching no shared rules; rule file / import → missing path. Contradictions, size → `bkit-audit-documentation`. **Done when:** `Instructions` row per host: files loaded, shared rules reached yes / no.
106
109
  - [ ] **Step 4 — Permissions:** Per host × layer: allow / ask / deny, default approval mode, sandbox mode, fetch / network allowlist. Findings: wildcard shell allow; arbitrary-text interpreter allow (e.g. `bash -c`, `node -e`, `python -c`); deny overridden by broader higher-precedence allow; approval-bypass mode in shared config outside a sandbox; fetch allowlist wider than needed per host matching rules (e.g. apex vs subdomain). `Parity` matrix: action × host → blocker: deny rule / hook / sandbox / prompt prose only / nothing. Minimum actions: force push, history rewrite, branch delete, hook skip (e.g. `--no-verify`), merge or push to protected branch, publish / release, delete outside the working tree, credential-file read (e.g. `.env*`), fetch to unlisted host, tool-server write to a shared or production system. Findings: blocked in one host, open in another; blocked by prompt prose only. **Done when:** `Permissions` row per host × layer; `Parity` matrix with no empty cell.
@@ -208,6 +211,13 @@ PENDING
208
211
 
209
212
  PENDING
210
213
 
214
+ ### Suggested Issues
215
+
216
+ <!-- prettier-ignore -->
217
+ | # | Title | Findings | Severity | Next Step | Reason |
218
+ | --- | --- | --- | --- | --- | --- |
219
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
220
+
211
221
  ### Process Improvements
212
222
 
213
223
  PENDING
@@ -221,6 +231,7 @@ PENDING
221
231
  - [ ] **Series:** `Parity` and tool-server hashes diffed against previous report's, or marked baseline.
222
232
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
223
233
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
234
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
224
235
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
225
236
 
226
237
  > `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
 
@@ -71,10 +71,13 @@
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 (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.
78
81
  - [ ] **Live Fetch:** Steps 2–9 — request public URLs, headers, and HTML, e.g. `curl`, a browser. Fallback: source read; live claims = hypotheses.
79
82
  - [ ] **Web:** Step 10 — fetch anchor standards. Fallback: versions recorded as unread.
80
83
 
@@ -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 — Public URLs:** List public URLs from sitemap if present, else crawl from home. Record production host and tools available in `Checked`. First: no preview deployment indexable (`X-Robots-Tag: noindex` or host deployment protection); crawled preview competes with production and can expose unreleased pages. Marketing site outside repo → name where; audit from live URL. **Done when:** host, URL list, preview verdict in `Public URLs`. No web origin → `N/A` and STOP. No indexable page → say so; `Indexing` still runs; steps needing indexable page skip with evidence in `Not Checked`.
101
104
  - [ ] **Step 3 — Indexing:** `robots.txt` + sitemap: present, valid, public URLs only. `lastmod` only when that page's content changes — trusted only when consistently accurate. Sitemap submitted in each webmaster console. Robots meta + `X-Robots-Tag` per page type: auth/previews `noindex`, public indexable. No `noindex` also `Disallow`ed: blocked crawler never sees `noindex` → URL can stay indexed from links. Canonicals: absolute, production host, one per page. Host canonicalisation: `http`→`https`, apex↔`www`, trailing-slash policy each one hop; HSTS set; sitemap uses canonical form only. Status codes: chain ≤1 hop, no loops, missing →404. Locales: `hreflang` per variant → existing pages; `hreflang="x-default"`; sets reciprocal and include self; canonical same-locale, never another locale; no forced `/` redirect by `Accept-Language` or IP — crawler without `Accept-Language` from one country (e.g. Googlebot) must see other locales. Content in HTML without JavaScript. Rendered HTML: one URL per page type — no-JS view vs engine render after JS (e.g. URL Inspection). Mobile/desktop same content when engine indexes mobile (e.g. Google). **Done when:** `Indexing` row per check: met / finding / not applicable (why).
102
105
  - [ ] **Step 4 — Metadata:** Indexable public page → title + description present, unique, right length. Open Graph + Twitter card tags; images exist, right size. `lang`, favicon, web manifest. Store listings → Smart App Banner (`apple-itunes-app`); `apple-app-site-association` + `assetlinks.json` reachable so search opens app. Link target screen → `bkit-audit-app-store`. **Done when:** `Metadata` row per page: tag · verdict, or skip in `Not Checked`.
@@ -205,6 +208,13 @@ PENDING
205
208
 
206
209
  PENDING
207
210
 
211
+ ### Suggested Issues
212
+
213
+ <!-- prettier-ignore -->
214
+ | # | Title | Findings | Severity | Next Step | Reason |
215
+ | --- | --- | --- | --- | --- | --- |
216
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
217
+
208
218
  ### Process Improvements
209
219
 
210
220
  PENDING
@@ -218,6 +228,7 @@ PENDING
218
228
  - [ ] **Series:** mention and citation share, and console query deltas, beside the previous report's numbers, or marked baseline.
219
229
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
220
230
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
231
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
221
232
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
222
233
 
223
234
  > `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
 
@@ -77,10 +77,13 @@ Tracking decays quietly: one-sided renames, funnel steps that stop after refacto
77
77
 
78
78
  **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.
79
79
 
80
+ **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.
81
+
80
82
  #### Core
81
83
 
82
84
  Always verify.
83
85
 
86
+ - [ ] **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.
84
87
  - [ ] **Web:** Step 18 — fetch anchor standards. Fallback: versions recorded as unread.
85
88
 
86
89
  #### Conditional
@@ -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 — Detect:** Find every analytics SDK, tag-manager snippet, and event call on web, native, and server — vendor packages, hosts, wrapper. Error-tracker SDKs are not product analytics. None → docs claiming tracking; unmet claim = finding → `bkit-audit-documentation`; then `N/A` and STOP. Record tools in `Checked`. **Done when:** surfaces in `Checked`, or `N/A` and STOP.
107
110
  - [ ] **Step 3 — Events:** Every code-sent event: name, fire site, property types = tracking plan as implemented. No written intended plan = finding (Step 4). **Done when:** `Events` lists every event and change since the previous run, or marked baseline.
108
111
  - [ ] **Step 4 — Plan:** Each business question: owner + map to named events, key events, custom dimensions. Event without question wastes limits = finding; question without event = gap. Intended plan `Events` compares to. **Done when:** `Plan` row per question: owner · events · verdict against `Events`.
@@ -244,6 +247,13 @@ PENDING
244
247
 
245
248
  PENDING
246
249
 
250
+ ### Suggested Issues
251
+
252
+ <!-- prettier-ignore -->
253
+ | # | Title | Findings | Severity | Next Step | Reason |
254
+ | --- | --- | --- | --- | --- | --- |
255
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
256
+
247
257
  ### Process Improvements
248
258
 
249
259
  PENDING
@@ -257,6 +267,7 @@ PENDING
257
267
  - [ ] **Series:** `Dashboards` shares and the `Container` diff beside previous report's, or marked baseline.
258
268
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
259
269
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
270
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
260
271
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
261
272
 
262
273
  > `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
 
@@ -77,11 +77,14 @@ One per annotation. **SILENT FAILURE** outranks every other verdict.
77
77
 
78
78
  **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.
79
79
 
80
+ **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.
81
+
80
82
  #### Core
81
83
 
82
84
  Always verify.
83
85
 
84
- - [ ] **CI Read:** Steps 2, 5, 11 — annotations and step logs for recent runs of every workflow, e.g. `gh api` check-run annotations, `gh run view --log`, GitLab job-trace API. Fallback: saved logs; runs not fetched `Not Checked`.
86
+ - [ ] **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.
87
+ - [ ] **CI Read:** Steps 2, 5, 11 — annotations and step logs for recent runs of every workflow, e.g. `gh api` check-run annotations, `gh run view --log`, GitLab job-trace API. 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: saved logs; runs not fetched `Not Checked`.
85
88
  - [ ] **Workflow Files:** Steps 4, 6, 8 — workflows, composite actions, reusable workflows on disk. Fallback: none.
86
89
  - [ ] **Web:** Steps 3, 12 — vendor changelog, runner-image announcements, anchor standards. Fallback: versions recorded as unread.
87
90
 
@@ -102,13 +105,13 @@ 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 — Collect:** No CI → one `N/A` row with evidence and STOP. Else read annotation lists for recent runs of every workflow, not last run of one pipeline. Deprecations surface on whichever workflow uses the old action. Include scheduled, manual, and bot-triggered runs. Collect mechanically, not by eye from the UI. Window = since previous report, and at least latest completed run of each workflow. Save list; diff vs previous report: new, resolved, persisting. Annotations capped (e.g. GitHub: 10 warnings, 10 errors, and 10 notices per step, and 50 per job). Step at cap → grep raw job log for warning and error markers; triage overflow. Record run ids and commit. Id, run, or path you cannot re-open → do not cite it. **Done when:** `Annotations` holds diff (new, resolved, persisting) and run ids.
107
110
  - [ ] **Step 3 — Deprecations:** Read vendor deprecation/retirement posts and runner-image announcements since previous report. List every dated change touching these workflows: runtimes, runner images, events, actions. Changelog notice precedes run notice. Each → DEPRECATION with date and bump. Dependency bot already tracks bump → say so; schedule rest next step. **Done when:** `Deprecations` row per dated change: what · date · bump · bot already tracking?
108
111
  - [ ] **Step 4 — Runtimes:** Every `uses:` (or the CI system's equivalent) in workflows, local composite actions, and reusable workflows — resolved version and declared runtime (e.g. `runs.using`). Action declaring removed runtime (e.g. `node20` after runners dropped it) runs on forced runtime with no opt-out → finding, unless seen working there. List leftover opt-out env keys that no longer change anything. **Done when:** `Runtimes` row per action: version · declared runtime · verdict, plus leftover keys.
109
112
  - [ ] **Step 5 — Log Warnings:** Some deprecations print only to log. Grep same runs' step logs for deprecation markers (e.g. `DeprecationWarning`, `[DEP0`, `npm warn deprecated`, `WARN deprecated`, `will be removed`) and CLI outdated notices (e.g. EAS, Expo, Vercel). Verdict each as if annotation. Agree with `bkit-audit-logs` which sweep owns each line — triage once. **Done when:** `Log Warnings` row per line: verdict or owning sweep.
110
113
  - [ ] **Step 6 — Static Analysis:** Run workflow linters every sweep, not only to verify a fix. Each new finding = annotation: shell issues in `run:` blocks, expression typos, template injection, excessive permissions, unpinned `uses:`. Grep workflows/scripts for deprecated workflow commands (e.g. GitHub Actions `::set-output`, `::save-state`, `::set-env`, `::add-path`) and opt-in re-enabling them (e.g. `ACTIONS_ALLOW_UNSECURE_COMMANDS`). Runner warns on some only at execute — conditional lane hides them. **Done when:** `Static Analysis` row per finding with verdict.
111
- - [ ] **Step 7 — Classify:** One verdict each from `Verdicts`. SILENT FAILURE on sight, e.g. GitHub `Unexpected input(s) '…', valid inputs are …` (misspelled input key, ignored); `No files were found with the provided path` (artifact never uploaded). No forced fit → OTHER. Destinations (next step; this run does not send): real defect → `docs/failures.jsonl` row to append (`@bkit-utility-update-failures` applies); SILENT FAILURE → root cause, fix, guard (`Silent Failures`); DEPRECATION → date and bump, dependency bot first; LINT WARNING → fix or why it stands; DEAD SUPPRESSION → delete directive, wrong-node flag; flake → `bkit-audit-flakes`; runtime error or log-sweep line → `bkit-audit-logs`; standing rule → sentence for testing or deployments doc; workflow change → recommendation needing explicit human confirmation; ACCEPTED → nothing, cite record. **Done when:** every annotation in `Annotations` has verdict and destination.
114
+ - [ ] **Step 7 — Classify:** One verdict each from `Verdicts`. SILENT FAILURE on sight, e.g. GitHub `Unexpected input(s) '…', valid inputs are …` (misspelled input key, ignored); `No files were found with the provided path` (artifact never uploaded). No forced fit → OTHER. Destinations (next step; this run does not send; the audit agent writes `docs/failures.jsonl` rows): real defect → `docs/failures.jsonl` row; SILENT FAILURE → root cause, fix, guard (`Silent Failures`); DEPRECATION → date and bump, dependency bot first; LINT WARNING → fix or why it stands; DEAD SUPPRESSION → delete directive, wrong-node flag; flake → `bkit-audit-flakes`; runtime error or log-sweep line → `bkit-audit-logs`; standing rule → sentence for testing or deployments doc; workflow change → recommendation needing explicit human confirmation; ACCEPTED → nothing, cite record. **Done when:** every annotation in `Annotations` has verdict and destination.
112
115
  - [ ] **Step 8 — Silent Failures:** Root-cause each SILENT FAILURE vs runner rules. Annotation = platform vocabulary symptom. Examples (GitHub Actions): `$GITHUB_ENV` blocklists some names (`NODE_OPTIONS` among them) — set as static job-level `env:` keys; `env` context unavailable to job-level `env:` value → shortened form resolves empty, fails quiet; step-level `env:` replaces job-level map (no merge) — overriding one key restates others; managed blocks revert in-marker edits — check key inside managed marker before recommending move. Other CI → equivalent (masked variables, non-merging env, platform-rewritten config). Report names guard fix should carry, proven red by reintroducing bug; where deleting mechanism leaves lane quiet and knob-less → second guard that replacement knob exists. Writing fix = next step. **Done when:** `Silent Failures` names root cause, fix, guard for each.
113
116
  - [ ] **Step 9 — Lint Node:** Lint annotation or in-code suppression → node rule fires on; count change if directive removed. Reason from per-file diagnostics; do not edit; do not whole-repo typecheck/lint for one file. Language server = one language; workflow files = text search. Dead disable at annotation line with effect further down (comment only) → DEAD SUPPRESSION on wrong node (live rule = LINT WARNING). **Done when:** `Lint` row per warning: node · directive · verdict.
114
117
  - [ ] **Step 10 — Matchers:** Problem matchers or annotation reporters for typecheck, lint, test output in CI (e.g. `tsc`, ESLint, Vitest). Without them warnings stay in logs — LINT WARNING under-counted. Confirm deprecated-API lint enabled (e.g. `@typescript-eslint/no-deprecated`). Deprecated framework API calls = code-side same deadline. **Done when:** `Matchers` names each reporter and deprecated-API rule: present or absent.
@@ -207,6 +210,13 @@ PENDING
207
210
 
208
211
  PENDING
209
212
 
213
+ ### Suggested Issues
214
+
215
+ <!-- prettier-ignore -->
216
+ | # | Title | Findings | Severity | Next Step | Reason |
217
+ | --- | --- | --- | --- | --- | --- |
218
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
219
+
210
220
  ### Process Improvements
211
221
 
212
222
  PENDING
@@ -221,6 +231,7 @@ PENDING
221
231
  - [ ] **Verified:** states what was checked locally and what still needs a real run.
222
232
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
223
233
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
234
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
224
235
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
225
236
 
226
237
  > `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.