@cbartens/bkit 5.2.3 → 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 (65) hide show
  1. package/.bkit/README.md +4 -2
  2. package/.bkit/core/.bkit/README.md +3 -1
  3. package/.bkit/core/.bkit/install.md +3 -3
  4. package/.bkit/core/.bkit/prompts.md +1 -1
  5. package/.bkit/core/.bkit/templates.md +19 -1
  6. package/.bkit/core/.bkit/workflows.md +7 -2
  7. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +9 -1
  8. package/.bkit/core/docs/templates/bkit-audit-adoption.md +9 -1
  9. package/.bkit/core/docs/templates/bkit-audit-agents.md +9 -1
  10. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +9 -1
  11. package/.bkit/core/docs/templates/bkit-audit-analytics.md +9 -1
  12. package/.bkit/core/docs/templates/bkit-audit-annotations.md +10 -2
  13. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +9 -1
  14. package/.bkit/core/docs/templates/bkit-audit-app-store.md +9 -1
  15. package/.bkit/core/docs/templates/bkit-audit-architecture.md +9 -1
  16. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +9 -1
  17. package/.bkit/core/docs/templates/bkit-audit-config.md +9 -1
  18. package/.bkit/core/docs/templates/bkit-audit-cost.md +10 -2
  19. package/.bkit/core/docs/templates/bkit-audit-coverage.md +9 -1
  20. package/.bkit/core/docs/templates/bkit-audit-database.md +9 -1
  21. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +9 -1
  22. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +9 -1
  23. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +9 -1
  24. package/.bkit/core/docs/templates/bkit-audit-documentation.md +9 -1
  25. package/.bkit/core/docs/templates/bkit-audit-duplication.md +9 -1
  26. package/.bkit/core/docs/templates/bkit-audit-failures.md +9 -1
  27. package/.bkit/core/docs/templates/bkit-audit-flakes.md +10 -2
  28. package/.bkit/core/docs/templates/bkit-audit-gates.md +9 -1
  29. package/.bkit/core/docs/templates/bkit-audit-issues.md +9 -1
  30. package/.bkit/core/docs/templates/bkit-audit-llm.md +9 -1
  31. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -2
  32. package/.bkit/core/docs/templates/bkit-audit-models.md +9 -1
  33. package/.bkit/core/docs/templates/bkit-audit-privacy.md +9 -1
  34. package/.bkit/core/docs/templates/bkit-audit-prompts.md +9 -1
  35. package/.bkit/core/docs/templates/bkit-audit-red-team.md +10 -2
  36. package/.bkit/core/docs/templates/bkit-audit-reliability.md +9 -1
  37. package/.bkit/core/docs/templates/bkit-audit-repo.md +10 -2
  38. package/.bkit/core/docs/templates/bkit-audit-security.md +10 -2
  39. package/.bkit/core/docs/templates/bkit-audit-slop.md +9 -1
  40. package/.bkit/core/docs/templates/bkit-audit-testing.md +10 -2
  41. package/.bkit/core/docs/templates/bkit-audit-usability.md +9 -1
  42. package/.bkit/core/engine/checks/tips/catalogue.ts +10 -0
  43. package/.bkit/core/engine/commands/install/upgrade.ts +9 -10
  44. package/.bkit/core/engine/commands/workflow/branches.ts +61 -7
  45. package/.bkit/core/engine/commands/workflow/repo.ts +16 -2
  46. package/.bkit/core/engine/commands/workflow/workflows.ts +4 -3
  47. package/.bkit/core/engine/shared/bkit-latest.ts +164 -0
  48. package/.bkit/core/engine/shared/timeouts.ts +6 -0
  49. package/.bkit/core/prompts/bkit-audit-generate.md +6 -4
  50. package/.bkit/core/workflows/bkit-build.md +1 -1
  51. package/.bkit/core/workflows/bkit-debug.md +1 -1
  52. package/.bkit/core/workflows/bkit-design.md +1 -1
  53. package/.bkit/core/workflows/bkit-plan.md +1 -1
  54. package/.bkit/core/workflows/bkit-ship.md +1 -1
  55. package/.bkit/templates/.husky/pre-push +7 -0
  56. package/.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs +115 -0
  57. package/CHANGELOG.md +17 -0
  58. package/dist/checks/tips/catalogue.js +9 -0
  59. package/dist/commands/install/upgrade.js +9 -10
  60. package/dist/commands/workflow/branches.js +54 -8
  61. package/dist/commands/workflow/repo.js +14 -2
  62. package/dist/commands/workflow/workflows.js +4 -3
  63. package/dist/shared/bkit-latest.js +150 -0
  64. package/dist/shared/timeouts.js +6 -0
  65. package/package.json +1 -1
@@ -85,7 +85,7 @@ One per probe, on the `Probes` row.
85
85
 
86
86
  Always verify.
87
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.
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 (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.
89
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.
90
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.
91
91
  - [ ] **Web:** Steps 2, 13 — each platform's penetration-testing page, and anchor standards. Fallback: policy unread → do not send probes; record why.
@@ -122,7 +122,7 @@ Verify only when applicable.
122
122
  - [ ] **Step 11 — Tools:** With attacker's token, as client that ignores rules: set fields allow-list excludes; pass victim's ids; change recurring record without required scope; send oversized arguments; repeat create to test idempotency key. **Done when:** `Probes` row per case, or skip with evidence no machine-client tools.
123
123
  - [ ] **Step 12 — Boundaries:** Script and markup in text fields; check render on web, native client, reply. Injection through search query and filters reaching search routine. Webhook endpoints: no signature = denial; wrong signature = same denial plus error log. Rate limits: documented thresholds fire, then stop. **Done when:** `Probes` row per boundary.
124
124
  - [ ] **Step 13 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per WSTG category (INFO, CONF, IDNT, ATHN, ATHZ, SESS, INPV, ERRH, CRYP, BUSL, CLNT, APIT), and per ATLAS tactic a model probe touched → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
125
- - [ ] **Step 14 — Anything Else:** (a) Everything changed since previous report's commit touching attack surface (routes, server actions, machine-client tools, webhooks, response headers, inbound handling, what client public key can reach; Step 3 diff = starting list) → one-line verdict each. (b) Bounded ~30 min pass: what senior penetration tester flags that no step asks; read since previous run (incidents, `bkit-audit-logs` reports, new `docs/failures.jsonl` rows, vendor status incidents) — what would no step catch? Probes these passes send follow rules, use identities made for it, go in `Probes`. Then delete every identity this run created with guarded delete (reaps tenant it would strand); confirm orphan sweep finds nothing left. Record where full request/response evidence is kept, for how long, redaction applied. **Done when:** `Beyond the Steps` holds both passes, or `none`; `Cleanup` confirms every identity this run created is gone. Class seen on 2 runs → propose step in `Process Improvements`. `Expected` names where finding goes, recommends safer fix. This run does not file or append ledger: `BROKE` → plan from this report, `docs/failures.jsonl` row to append later, regression test (ideally deployed boundary) so `bkit-audit-testing` keeps it fixed; `HELD` with no test → `bkit-audit-testing`; model result → `bkit-audit-llm`, against finding it tested; `STILL BROKE` → original finding, with retest and fix commit; `INCONCLUSIVE` → next run's Step 2 suspicion list, with what blocked; `OTHER` → report, second run proposes verdict; vulnerability in database product itself, not project's use → vendor per that vendor's testing page, plus this report; stop condition → remaining probes stopped, stop recorded in `Scope`.
125
+ - [ ] **Step 14 — Anything Else:** (a) Everything changed since previous report's commit touching attack surface (routes, server actions, machine-client tools, webhooks, response headers, inbound handling, what client public key can reach; Step 3 diff = starting list) → one-line verdict each. (b) Bounded ~30 min pass: what senior penetration tester flags that no step asks; read since previous run (incidents, `bkit-audit-logs` reports, new `docs/failures.jsonl` rows, vendor status incidents) — what would no step catch? Probes these passes send follow rules, use identities made for it, go in `Probes`. Then delete every identity this run created with guarded delete (reaps tenant it would strand); confirm orphan sweep finds nothing left. Record where full request/response evidence is kept, for how long, redaction applied. **Done when:** `Beyond the Steps` holds both passes, or `none`; `Cleanup` confirms every identity this run created is gone. Class seen on 2 runs → propose step in `Process Improvements`. `Expected` names where finding goes, recommends safer fix. This run does not file; the audit agent writes `docs/failures.jsonl` rows: `BROKE` → plan from this report, `docs/failures.jsonl` row, regression test (ideally deployed boundary) so `bkit-audit-testing` keeps it fixed; `HELD` with no test → `bkit-audit-testing`; model result → `bkit-audit-llm`, against finding it tested; `STILL BROKE` → original finding, with retest and fix commit; `INCONCLUSIVE` → next run's Step 2 suspicion list, with what blocked; `OTHER` → report, second run proposes verdict; vulnerability in database product itself, not project's use → vendor per that vendor's testing page, plus this report; stop condition → remaining probes stopped, stop recorded in `Scope`.
126
126
 
127
127
  ### 🔒 Gate 2: Probes Check
128
128
 
@@ -201,6 +201,13 @@ PENDING
201
201
 
202
202
  PENDING
203
203
 
204
+ ### Suggested Issues
205
+
206
+ <!-- prettier-ignore -->
207
+ | # | Title | Findings | Severity | Next Step | Reason |
208
+ | --- | --- | --- | --- | --- | --- |
209
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
210
+
204
211
  ### Process Improvements
205
212
 
206
213
  PENDING
@@ -214,6 +221,7 @@ PENDING
214
221
  - [ ] **Cleanup:** states that every identity this run created is deleted, and where redacted evidence is kept.
215
222
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
216
223
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
224
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
217
225
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
218
226
 
219
227
  > `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.
@@ -77,7 +77,7 @@ Failure paths are least-tested: happy path is tested; vendor outage stays unwalk
77
77
 
78
78
  Always verify.
79
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.
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.
81
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.
82
82
  - [ ] **Web:** Step 15 — fetch anchor standards. Fallback: versions recorded as unread.
83
83
 
@@ -202,6 +202,13 @@ PENDING
202
202
 
203
203
  PENDING
204
204
 
205
+ ### Suggested Issues
206
+
207
+ <!-- prettier-ignore -->
208
+ | # | Title | Findings | Severity | Next Step | Reason |
209
+ | --- | --- | --- | --- | --- | --- |
210
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
211
+
205
212
  ### Process Improvements
206
213
 
207
214
  PENDING
@@ -216,6 +223,7 @@ PENDING
216
223
  - [ ] **Game Day:** states the date and outcome of the last game day, or that none is recorded, and names the next dependency.
217
224
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
218
225
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
226
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
219
227
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
220
228
 
221
229
  > `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.
@@ -87,7 +87,7 @@ Every task leaves a worktree, branch, stash, or scratch directory; nothing's job
87
87
 
88
88
  Always verify.
89
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.
90
+ - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
91
91
  - [ ] **Git:** Steps 2–7, 9 — local checkout, worktrees, branches, stashes. Fallback: none; no checkout → `N/A` and STOP.
92
92
  - [ ] **Host API:** Steps 4, 8 — read-only, e.g. `gh api`. Fallback: local git only; remote branches, pull requests, and settings `Not Checked`.
93
93
  - [ ] **Web:** Step 10 — fetch anchor standards. Fallback: versions recorded as unread.
@@ -118,7 +118,7 @@ Verify only when applicable.
118
118
  - [ ] **Step 6 — Leftovers:** Untracked (`git status --porcelain`) and ignored (`git ls-files --others --ignored --exclude-standard --directory`), each sized. Sort: regenerable (dependencies, task cache, coverage, test results, native build folders, tool caches) — REMOVE is safe, report the size; hand-made (notes, plans, backups, logs, scripts in the scratch directory) — group by age and type; open issue or plan references → KEEP; produced and not cleaned up — leftover REMOVE, producer is finding; stranded at root — find writer; tool defaulting to root → point elsewhere. Ignore file: rules matching nothing; leftovers untracked because no rule covers them. Scan secrets and personal data before any MOVE or REMOVE on scratch, root, or plan logs; scanner reports outside repo. Personal-data hits are candidates: test fixtures carry fake addresses. A real hit in a tracked file is not fixed by removing the file — it stays in history. Name the file and line, never the value. Hooks: hooks path resolves at the hook directory, each hook executable, and the install script installs them. A checkout where hooks silently do not run looks clean here while skipping every pre-commit control. **Done when:** `Leftovers` grouped with verdicts; scan result named; sizes in `Totals`.
119
119
  - [ ] **Step 7 — Layout:** Read where tracked files belong; find misfits. Size: largest blobs at `HEAD`. Committed generated output/logs → MOVE or REMOVE candidates. Record pack size as series. History size: deleted file still grows clones — repository sizer or blob sizes across all refs. Images/logs → recommend large-file storage or ignore; history rewrite owner's call (ASK). Secrets in history: scan all refs; list every sensitive file ever added (example env files expected). Verified live credential → `CRITICAL`: rotation first (rewrite does not reach existing clones). Name file and commit, never value. Toolchain agreement: runtime pin, engine field, package-manager field, CI setup, host build image, native build config; workspace dependency-version linter for cross-workspace drift or catalog bypass. Docs-versus-files → documentation audit; this step files versus each other. Accidental publish: every workspace package not meant for a registry is marked unpublishable (e.g. npm `private: true`, Cargo `publish = false`), and the root states the licence position. Attributes: end-of-line, generated-file linguist marks so review diffs collapse them, binary marks on images, and an editor config that agrees with the formatter. Placement: root files belonging to app/package, finished one-off scripts, drafts beside final doc, unlinked archive folders, near-empty packages. Naming: folders/files breaking neighbour conventions. Contribution scaffolding: owners file, pull-request and issue templates, contributing note — present and true; whether team needs them → owner (ASK). Template describing unfollowed process → MOVE or REMOVE. Owners file: propose paths that weaken a gate when edited → required human review; once exists, host owners-errors API must return none. Unimported file → dead-code audit; misplaced-but-wrong doc → documentation audit. **Done when:** `Layout` rows; pack size and largest history blobs in `Totals`.
120
120
  - [ ] **Step 8 — Posture:** Config audit asks settings vs docs; this step asks vs anchor standards. Read that audit's latest report first; do not duplicate findings. Shared settings: every run checks (local or cloud). Scorecard: each check's score as series. Keep binary artifacts, branch protection, code review, dependency-update tool, security policy here; token permissions, pinned dependencies, dangerous workflow → `bkit-audit-security`. Branch protection (integration, production): pull request required, required check required, force-push and deletion blocked, squash-only or linear history, bypass list — compare with production-merge-requires-PR rule. Security settings: secret scanning and push protection on; who may bypass push protection. Private repo: push protection may need paid secret-protection plan — say so if plan excludes it. Push protection blocks at server (hook bypass does not reach). Also dependency alerts, private vulnerability reporting, default automation token read-only, automation creating/approving pull requests off. Disclosure: security policy or private vulnerability reporting, and `/.well-known/security.txt` on production web origin with RFC contact/expiry fields and expiry ahead. People, 2FA, deploy keys, long-lived tokens → security audit; automation secrets/variables → config audit. Read their latest reports; confirm 2FA enforcement recorded. List accumulators like branches: installed apps and permissions, webhooks, environments. App over-scoped or webhook to unused service → REMOVE or ASK. **Done when:** `Posture` holds each setting met / finding / not applicable; scores in `Totals`.
121
- - [ ] **Step 9 — Verify:** Git state changes hourly. Record when each check ran; re-check every RESCUE and REMOVE at end. No finding without re-checkable evidence: command and output, or `file:line`. Destinations (name; do not act): REMOVE → exact command next step would run, batched for one review; RESCUE → what it holds, who would know, decision (push and open pull request, or drop on purpose); MOVE → move and every reference to update; ASK → who would know and question; OTHER → why no verdict fits; leftover something keeps producing → `docs/failures.jsonl` row against producer (report; do not write ledger); missing/stale ignore rule → line to add or remove; code or config nothing reaches → `bkit-audit-dead-code`; a doc that is wrong, not misplaced → `bkit-audit-documentation`; dependency-bot branch → `bkit-audit-dependencies`; secret in history, log, or leftover → `bkit-audit-security`, rotation first, file and commit only; personal data in log or leftover → `bkit-audit-privacy`; repository setting below standard → setting to change for owner, doc drift → `bkit-audit-config`; workflow-level scorecard failure → `bkit-audit-security`; toolchain versions disagree → file to change; host setting → `bkit-audit-config`; dependency versions → `bkit-audit-dependencies`. **Done when:** every RESCUE and REMOVE re-checked, with time, verdict, and destination.
121
+ - [ ] **Step 9 — Verify:** Git state changes hourly. Record when each check ran; re-check every RESCUE and REMOVE at end. No finding without re-checkable evidence: command and output, or `file:line`. Destinations (name; do not act; the audit agent writes `docs/failures.jsonl` rows): REMOVE → exact command next step would run, batched for one review; RESCUE → what it holds, who would know, decision (push and open pull request, or drop on purpose); MOVE → move and every reference to update; ASK → who would know and question; OTHER → why no verdict fits; leftover something keeps producing → `docs/failures.jsonl` row against producer; missing/stale ignore rule → line to add or remove; code or config nothing reaches → `bkit-audit-dead-code`; a doc that is wrong, not misplaced → `bkit-audit-documentation`; dependency-bot branch → `bkit-audit-dependencies`; secret in history, log, or leftover → `bkit-audit-security`, rotation first, file and commit only; personal data in log or leftover → `bkit-audit-privacy`; repository setting below standard → setting to change for owner, doc drift → `bkit-audit-config`; workflow-level scorecard failure → `bkit-audit-security`; toolchain versions disagree → file to change; host setting → `bkit-audit-config`; dependency versions → `bkit-audit-dependencies`. **Done when:** every RESCUE and REMOVE re-checked, with time, verdict, and destination.
122
122
  - [ ] **Step 10 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per Scorecard check and per baseline control in sets this audit touches (e.g. OSPS-AC, OSPS-BR-07, OSPS-GV, OSPS-LE, OSPS-VM) → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
123
123
  - [ ] **Step 11 — Anything Else:** (a) Everything changed since previous report's commit touching the repository itself (new top-level files and folders, workspaces, ignore, and attribute files, hooks, branch, and ruleset settings, host apps, webhooks, environments, anything new that writes to the scratch directory or the root) → one-line verdict each. (b) Bounded ~30 min pass: what a senior platform engineer flags that no step asks; read what happened since previous run (incidents, `bkit-audit-logs` reports, new `docs/failures.jsonl` rows, vendor status incidents) — what would no step catch? **Done when:** `Beyond the Steps` holds both passes, or `none`. Class seen on 2 runs → propose step in `Process Improvements`.
124
124
 
@@ -205,6 +205,13 @@ PENDING
205
205
 
206
206
  PENDING
207
207
 
208
+ ### Suggested Issues
209
+
210
+ <!-- prettier-ignore -->
211
+ | # | Title | Findings | Severity | Next Step | Reason |
212
+ | --- | --- | --- | --- | --- | --- |
213
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
214
+
208
215
  ### Process Improvements
209
216
 
210
217
  PENDING
@@ -218,6 +225,7 @@ PENDING
218
225
  - [ ] **Series:** `Totals` beside previous report's numbers, or marked baseline.
219
226
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
220
227
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
228
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
221
229
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
222
230
 
223
231
  > `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.
@@ -87,7 +87,7 @@ Fixes land on call sites a sweep already knew; the doc records the rule. A later
87
87
 
88
88
  Always verify.
89
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.
90
+ - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
91
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.
92
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.
93
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`.
@@ -138,7 +138,7 @@ Verify only when applicable.
138
138
  - [ ] **Step 21 — Native:** Native app: session tokens in secure store (Keychain, Keystore), not prefs. No tokens/PII in device logs, backups, sensitive-screen screenshots. Auth callbacks/deep links: verified universal/app links, not claimable custom scheme; deep-link params = untrusted input. Association files served/valid → `bkit-audit-config`. No cleartext exception. OTA code signing on, or record plan lacks it. **Done when:** `Native` row per control group, or skip with evidence no native app.
139
139
  - [ ] **Step 22 — Disclosure:** Published vuln disclosure policy; `/.well-known/security.txt` with monitored `Contact`, unexpired `Expires` (RFC 9116). Current security incident runbook: paging, Step 15 key revocation, session revoke, breach-notification duties per jurisdiction. General incident → `bkit-audit-reliability`; notification timelines → `bkit-audit-privacy`. Last tested restore date from newest `bkit-audit-database` report. **Done when:** each requirement met or finding, in `Checked`.
140
140
  - [ ] **Step 23 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: row per ASVS chapter, Top 10 category, API Security Top 10 risk, (native app) MASVS group → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. Project security checklist/skill covers current releases; lag → name which. **Done when:** no empty row.
141
- - [ ] **Step 24 — Anything Else:** (a) Security-touching changes since previous commit (routes, server actions, machine-client tools, webhooks, processors, workflows, env vars, platforms, outbound hosts, native features) → one-line verdict each vs Step 23 chapter list. (b) ~30 min bounded pass: senior appsec flags no step asks; since previous run read incidents, `bkit-audit-logs`, new `docs/failures.jsonl`, vendor status — what would no step catch? **Done when:** `Beyond the Steps` holds both passes, or `none`. Class seen on 2 runs → propose step in `Process Improvements`; literal signature class → Step 2 row instead. `Expected` on each finding: destination + safer fix. This run does not file, append ledger, or edit doc: security hole → plan from report; discovered bug → `docs/failures.jsonl` row to append later; storage-policy gap (Step 9) → also `bkit-audit-database`; deletion gap (Step 19) → also `bkit-audit-privacy`; prompt-injection model half (Step 10) → `bkit-audit-llm`, not re-derived; live hostile check → `bkit-audit-red-team`; uncovered trust boundary (Step 3) → proposed doc update, not applied; workflow change (Step 17) → human confirmation, never edit workflow; new literal class → proposed Step 2 row under `Process Improvements`.
141
+ - [ ] **Step 24 — Anything Else:** (a) Security-touching changes since previous commit (routes, server actions, machine-client tools, webhooks, processors, workflows, env vars, platforms, outbound hosts, native features) → one-line verdict each vs Step 23 chapter list. (b) ~30 min bounded pass: senior appsec flags no step asks; since previous run read incidents, `bkit-audit-logs`, new `docs/failures.jsonl`, vendor status — what would no step catch? **Done when:** `Beyond the Steps` holds both passes, or `none`. Class seen on 2 runs → propose step in `Process Improvements`; literal signature class → Step 2 row instead. `Expected` on each finding: destination + safer fix. This run does not file or edit doc; the audit agent writes `docs/failures.jsonl` rows: security hole → plan from report; discovered bug → `docs/failures.jsonl` row; storage-policy gap (Step 9) → also `bkit-audit-database`; deletion gap (Step 19) → also `bkit-audit-privacy`; prompt-injection model half (Step 10) → `bkit-audit-llm`, not re-derived; live hostile check → `bkit-audit-red-team`; uncovered trust boundary (Step 3) → proposed doc update, not applied; workflow change (Step 17) → human confirmation, never edit workflow; new literal class → proposed Step 2 row under `Process Improvements`.
142
142
 
143
143
  ### 🔒 Gate 2: Probes Check
144
144
 
@@ -255,6 +255,13 @@ PENDING
255
255
 
256
256
  PENDING
257
257
 
258
+ ### Suggested Issues
259
+
260
+ <!-- prettier-ignore -->
261
+ | # | Title | Findings | Severity | Next Step | Reason |
262
+ | --- | --- | --- | --- | --- | --- |
263
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
264
+
258
265
  ### Process Improvements
259
266
 
260
267
  PENDING
@@ -268,6 +275,7 @@ PENDING
268
275
  - [ ] **Classes:** every standing class has a row, including the clean ones.
269
276
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
270
277
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
278
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
271
279
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
272
280
 
273
281
  > `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.
@@ -82,7 +82,7 @@ Each suppression made sense in one PR; nothing re-reads them. Glob hiding one de
82
82
 
83
83
  Always verify.
84
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.
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.
86
86
  - [ ] **Scanner:** Steps 2–4 — pinned in manifest, e.g. `slop-scan`. Fallback: skip scanner steps; run code / config steps.
87
87
  - [ ] **Worktree:** Steps 2–8 — detached worktree off default branch. Fallback: Steps 5–7 read-only in main checkout; Steps 3, 8 `Not Checked`.
88
88
  - [ ] **Git History:** Steps 5, 8 — full history for blame and churn. Fallback: ages and churn `Not Checked`.
@@ -181,6 +181,13 @@ PENDING
181
181
 
182
182
  PENDING
183
183
 
184
+ ### Suggested Issues
185
+
186
+ <!-- prettier-ignore -->
187
+ | # | Title | Findings | Severity | Next Step | Reason |
188
+ | --- | --- | --- | --- | --- | --- |
189
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
190
+
184
191
  ### Process Improvements
185
192
 
186
193
  PENDING
@@ -194,6 +201,7 @@ PENDING
194
201
  - [ ] **Series:** `Counts` beside previous report's counts, or marked baseline.
195
202
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
196
203
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
204
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
197
205
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
198
206
 
199
207
  > `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.
@@ -78,7 +78,7 @@ Green suite = tests passed — not that they could fail, that every promise has
78
78
 
79
79
  Always verify.
80
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.
81
+ - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
82
82
  - [ ] **Git:** Steps 1, 14 — `git rev-parse`, diff since previous report. Fallback: run marked baseline; ages and the what-changed pass `Not Checked`.
83
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`.
84
84
  - [ ] **Web:** Step 13 — fetch anchor standards. Fallback: versions recorded as unread.
@@ -152,7 +152,7 @@ Verify only when applicable.
152
152
  - [ ] **Step 9 — Runs:** Every test file has a lane. Names putting file outside every run (see Step 6). Suites skipping when setup fails instead of failing. Skips (e.g. `test.skip`, `fixme`, `describe.skip`, `pytest.mark.skip`), env-dependent skips. Stale build output runner now collects (e.g. Vitest 4 and later does not ignore `dist/` by default). The 20 slowest tests per tier from runner reports. Slow test = next one someone skips. **Done when:** rows in `Runs`.
153
153
  - [ ] **Step 10 — Time:** Date/calendar/timezone logic → unit tests with `TZ` non-UTC zone observing DST (e.g. `Pacific/Auckland`, `America/St_Johns`) on process before workers spawn. Then date-touching suites with clock pinned near month end and DST change (e.g. `vi.setSystemTime`, Playwright `page.clock`), throwaway setup removed after. Record tests whose result changes. List suites never pinning clock. **Done when:** results in `Time`, or skip with evidence.
154
154
  - [ ] **Step 11 — Copies:** Same test procedure in several places (open dialog, create user, read credentials). Disagreeing copies first. Agreeing copies need single owner only if likely to drift. One owner created → next step adds guard failing on new copy. Code graph finds copied functions; copied statement sequences need syntax-tree scan. Product-code duplication → `bkit-audit-duplication`. **Done when:** groups in `Copies`, or `none`.
155
- - [ ] **Step 12 — Route:** No finding without re-checkable evidence: `file:line`, or query, run id, measurement, plus tool. Language-server empty inconclusive → corroborate text search. Report names where each finding goes; sending is next step. App bug → `docs/failures.jsonl` row and issue; security bugs flagged for project security milestone. Missing test small → test to write. Missing test large → follow-up issue. Cannot-fail test → fix, positive control (break code, watch red, restore), `docs/failures.jsonl` row. Behaviour no recorded intent → question for maintainer; do not guess from code. Tier too high → lower-tier test to write; higher-tier stays until new one seen red. Equivalent mutant → disable comment to add. Timezone/date result → app bug if app wrong; else test fix and `docs/failures.jsonl` row. Flaky → `bkit-audit-flakes`. Coverage floor move → `bkit-audit-coverage`. Check as CI gate → `bkit-audit-gates`. Dead code → `bkit-audit-dead-code`. **Done when:** every finding's Expected names destination.
155
+ - [ ] **Step 12 — Route:** No finding without re-checkable evidence: `file:line`, or query, run id, measurement, plus tool. Language-server empty inconclusive → corroborate text search. Report names where each finding goes; sending is next step; the audit agent writes `docs/failures.jsonl` rows. App bug → `docs/failures.jsonl` row and issue; security bugs flagged for project security milestone. Missing test small → test to write. Missing test large → follow-up issue. Cannot-fail test → fix, positive control (break code, watch red, restore), `docs/failures.jsonl` row. Behaviour no recorded intent → question for maintainer; do not guess from code. Tier too high → lower-tier test to write; higher-tier stays until new one seen red. Equivalent mutant → disable comment to add. Timezone/date result → app bug if app wrong; else test fix and `docs/failures.jsonl` row. Flaky → `bkit-audit-flakes`. Coverage floor move → `bkit-audit-coverage`. Check as CI gate → `bkit-audit-gates`. Dead code → `bkit-audit-dead-code`. **Done when:** every finding's Expected names destination.
156
156
  - [ ] **Step 13 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per OWASP API Security Top 10 item and ASVS chapter (attack rows Step 3), per test-smell in catalogue (shapes Step 7) → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. Do not change steps during run. **Done when:** no empty row.
157
157
  - [ ] **Step 14 — Anything Else:** (a) Everything since previous report commit touching suite (test files/helpers, fixtures/factories, unit/browser/device runner config, CI test lanes, routes/workers/migrations/external services tests cover) → one-line verdict each. (b) Bounded ~30 min pass: senior test engineer flags outside steps; read since previous run (incidents, `bkit-audit-logs`, new `docs/failures.jsonl`, vendor status) — what would no step catch? **Done when:** `Beyond the Steps` holds both passes, or `none`. Class seen on 2 runs → propose step in `Process Improvements`.
158
158
 
@@ -251,6 +251,13 @@ PENDING
251
251
 
252
252
  PENDING
253
253
 
254
+ ### Suggested Issues
255
+
256
+ <!-- prettier-ignore -->
257
+ | # | Title | Findings | Severity | Next Step | Reason |
258
+ | --- | --- | --- | --- | --- | --- |
259
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
260
+
254
261
  ### Process Improvements
255
262
 
256
263
  PENDING
@@ -264,6 +271,7 @@ PENDING
264
271
  - [ ] **Series:** test count and runtime per tier, and both scores, beside previous report's numbers, or marked baseline.
265
272
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
266
273
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
274
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
267
275
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
268
276
 
269
277
  > `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.
@@ -78,7 +78,7 @@ Automated checks never look at a screen. They pass when a title is centred on on
78
78
 
79
79
  Always verify.
80
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.
81
+ - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
82
82
  - [ ] **Screens:** Steps 2, 7–14 — open product (local or existing preview). Fallback: drawings and source only; live claims = hypotheses.
83
83
  - [ ] **Drawings:** Steps 5, 7, 9 — reference drawings readable. Fallback: live vs live only; drawing comparison `Not Checked`.
84
84
  - [ ] **Web:** Step 15 — fetch anchor standards. Fallback: versions recorded as unread.
@@ -218,6 +218,13 @@ PENDING
218
218
 
219
219
  PENDING
220
220
 
221
+ ### Suggested Issues
222
+
223
+ <!-- prettier-ignore -->
224
+ | # | Title | Findings | Severity | Next Step | Reason |
225
+ | --- | --- | --- | --- | --- | --- |
226
+ | PENDING | PENDING | PENDING | PENDING | PENDING | PENDING |
227
+
221
228
  ### Process Improvements
222
229
 
223
230
  PENDING
@@ -231,6 +238,7 @@ PENDING
231
238
  - [ ] **Series:** every series beside previous report's numbers, or marked baseline.
232
239
  - [ ] **Writes:** only this report and template `Project Instructions` changed; throwaway worktrees / remote targets removed.
233
240
  - [ ] **Process Improvements:** `Universal` = proposed step changes, template untouched; `Project` = edits applied below `bkit:end`; each `none` if empty.
241
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
234
242
  - [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
235
243
 
236
244
  > `Project Instructions` below `bkit:end` are consumer-owned — `bkit install` never overwrites them, `bkit check` drift stays clean. Add project-specific tools, paths, commands, and checks there, keyed by section or step title; never results.
@@ -329,6 +329,16 @@ export const SETUP_TIPS: readonly SetupTip[] = [
329
329
  steps: "`.bkit/templates.md` § Prettier tables.",
330
330
  fires: (cwd) => !exists(cwd, "scripts/prettier/bkit-insert-ignore.mjs"),
331
331
  },
332
+ {
333
+ id: "tmp-prune",
334
+ title: "Clear out old scratch files",
335
+ line: "Scratch files agents leave in tmp/ are never cleared, so the folder keeps growing. Add the clean-up that runs when you push.",
336
+ why: "Agents leave logs and scratch files in tmp/ on every run. Each push deletes the ones untouched for a week, so the folder stays small without anyone thinking about it.",
337
+ ask: "Copy .bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs to scripts/cleanup/, then copy the `tmp/ prune` block from .bkit/templates/.husky/pre-push into .husky/pre-push above the gates.",
338
+ steps: "`.bkit/templates.md` § tmp/ prune.",
339
+ fires: (cwd) =>
340
+ exists(cwd, ".husky/pre-push") && !exists(cwd, "scripts/cleanup/bkit-tmp-prune.mjs"),
341
+ },
332
342
 
333
343
  // --- setup: only some setups -----------------------------------------------------------
334
344
  {
@@ -49,6 +49,7 @@ import {
49
49
  runUpgradeAdvisories,
50
50
  } from "./install.js";
51
51
  import { setLogPrefix } from "../../shared/log-prefix.js";
52
+ import { BKIT_PACKAGE, lookupLatestPublished } from "../../shared/bkit-latest.js";
52
53
  import {
53
54
  getInstallManifest,
54
55
  getModuleManifest,
@@ -536,18 +537,17 @@ export function updateCanonicalHashesAfterUpgrade(
536
537
  * registry auth). Hard-exits with guidance on failure — the caller has nothing
537
538
  * to fall back to.
538
539
  */
539
- async function resolveLatestPublishedVersion(cwd: string): Promise<string> {
540
- const { spawnSync } = await import("node:child_process");
541
- const r = spawnSync("pnpm", ["view", "@cbartens/bkit", "version"], { cwd, encoding: "utf-8" });
542
- if (r.status !== 0 || !r.stdout || !r.stdout.trim()) {
540
+ function resolveLatestPublishedVersion(cwd: string): string {
541
+ const latest = lookupLatestPublished(cwd, null);
542
+ if (latest === null) {
543
543
  console.error(
544
- `${LOG_PREFIX} could not resolve the latest @cbartens/bkit version from the registry ` +
545
- `(pnpm view exit ${r.status ?? "null"}). Check your network / registry access, ` +
544
+ `${LOG_PREFIX} could not resolve the latest ${BKIT_PACKAGE} version from the registry ` +
545
+ `(pnpm view failed). Check your network / registry access, ` +
546
546
  `or pin a version with --to=<version>.`,
547
547
  );
548
548
  process.exit(1);
549
549
  }
550
- return r.stdout.trim();
550
+ return latest;
551
551
  }
552
552
 
553
553
  /**
@@ -562,9 +562,8 @@ async function resolveLatestPublishedVersion(cwd: string): Promise<string> {
562
562
  */
563
563
  export async function runSelfBump(flags: UpgradeFlags, cwd: string): Promise<boolean> {
564
564
  const installed = getInstallingVersion();
565
- // --latest needs async registry resolution, but planSelfBump's injected resolver
566
- // is sync; resolve the latest first (only when asked), then feed it a constant.
567
- const latestVersion = flags.latest ? await resolveLatestPublishedVersion(cwd) : "";
565
+ // Resolve the latest first (only when asked), then feed planSelfBump a constant.
566
+ const latestVersion = flags.latest ? resolveLatestPublishedVersion(cwd) : "";
568
567
  const resolvedPlan = planSelfBump(
569
568
  installed,
570
569
  { toVersion: flags.toVersion, latest: flags.latest },
@@ -29,6 +29,7 @@ import {
29
29
  type FlagValue,
30
30
  type RunContext,
31
31
  } from "../lib.js";
32
+ import { bkitVersionStatus, type BkitVersionStatus } from "../../shared/bkit-latest.js";
32
33
  import { TIMEOUTS } from "../../shared/timeouts.js";
33
34
  import { commitBookkeeping } from "./ledgers.js";
34
35
  import { acquireDevLock, lockRoot, releaseLock, resolveMonth, workflowLockPath } from "./locks.js";
@@ -354,7 +355,17 @@ export function resolveRebase(
354
355
 
355
356
  const ANCHOR_OPEN = "<!-- bkit:anchor";
356
357
  const ANCHOR_CLOSE = "-->";
357
- export const ANCHOR_FIELDS = ["baseSha", "baseRef", "designPath", "designBaseSha"] as const;
358
+ /** Ends the visible line a stamp writes under the block when the doc came from an outdated bkit. */
359
+ const OUTDATED_MARK = "<!-- bkit:outdated -->";
360
+ const OUTDATED_LINE = new RegExp(`^.*${OUTDATED_MARK}\n(?:\n)?`, "gm");
361
+ export const ANCHOR_FIELDS = [
362
+ "baseSha",
363
+ "baseRef",
364
+ "designPath",
365
+ "designBaseSha",
366
+ "bkitVersion",
367
+ "bkitLatest",
368
+ ] as const;
358
369
  export type AnchorField = (typeof ANCHOR_FIELDS)[number];
359
370
 
360
371
  /** Lines of `text` with whether each sits inside an anchor block (a `sed '/open/,/close/'` range). */
@@ -390,20 +401,49 @@ export function readAnchor(text: string): Partial<Record<AnchorField, string>> {
390
401
  return out;
391
402
  }
392
403
 
393
- /** `text` with a fresh anchor block on top and every prior one removed, so re-stamping is idempotent. */
404
+ /**
405
+ * The bkit release a doc is being generated from, for its anchor: undefined when
406
+ * this repo has no `.bkit/version` pin (nothing to record). Asks the registry for
407
+ * the newest release at most once a day; offline leaves `latest` null.
408
+ */
409
+ export function anchorBkitStatus(cwd: string): BkitVersionStatus | undefined {
410
+ const status = bkitVersionStatus(
411
+ git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd,
412
+ git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]),
413
+ );
414
+ return status.version === null ? undefined : status;
415
+ }
416
+
417
+ /**
418
+ * `text` with a fresh anchor block on top and every prior one removed, so re-stamping
419
+ * is idempotent. With `bkit`, the block records the release the doc came from and the
420
+ * newest one (empty when unknown); an outdated release adds one visible warning line
421
+ * under the block, replaced or dropped by the next stamp like the block itself.
422
+ */
394
423
  export function stampAnchor(
395
424
  text: string,
396
425
  baseSha: string,
397
426
  design?: { path: string; baseSha: string },
398
427
  baseRef: string = UPSTREAM,
428
+ bkit?: BkitVersionStatus,
399
429
  ): string {
400
430
  const header = [ANCHOR_OPEN, `baseSha: ${baseSha}`, `baseRef: ${baseRef}`];
401
431
  if (design) header.push(`designPath: ${design.path}`, `designBaseSha: ${design.baseSha}`);
432
+ if (bkit) header.push(`bkitVersion: ${bkit.version ?? ""}`, `bkitLatest: ${bkit.latest ?? ""}`);
402
433
  header.push(ANCHOR_CLOSE);
403
- const body = anchorLines(text)
434
+ let body = anchorLines(text)
404
435
  .filter((l) => !l.inBlock)
405
436
  .map((l) => (l.last ? l.line : `${l.line}\n`))
406
- .join("");
437
+ .join("")
438
+ .replace(OUTDATED_LINE, "");
439
+ if (bkit?.outdated === true) {
440
+ // Blank lines on both sides of the warning, as prettier writes them.
441
+ header.push(
442
+ "",
443
+ `> **Outdated bkit:** generated with bkit ${bkit.version} while ${bkit.latest} was out, so its workflow and template text may be stale. Upgrade with \`pnpm bkit upgrade --latest\` and regenerate if that matters. ${OUTDATED_MARK}`,
444
+ );
445
+ body = `\n${body.replace(/^\n+/, "")}`;
446
+ }
407
447
  return `${header.join("\n")}\n${body}`;
408
448
  }
409
449
 
@@ -1191,8 +1231,10 @@ function anchorStampVerb(ctx: RunContext): number {
1191
1231
  baseSha: readAnchor(fs.readFileSync(designFile, "utf-8")).baseSha ?? "",
1192
1232
  }
1193
1233
  : undefined;
1234
+ const bkit = anchorBkitStatus(ctx.cwd);
1235
+ if (bkit?.advisory) ctx.log(bkit.advisory);
1194
1236
  const before = fs.readFileSync(file, "utf-8");
1195
- const after = stampAnchor(before, baseSha, design, baseRef);
1237
+ const after = stampAnchor(before, baseSha, design, baseRef, bkit);
1196
1238
  // Temp file + rename: a crash mid-write never leaves a half-stamped doc.
1197
1239
  const tmp = `${file}.bkit-anchor.tmp`;
1198
1240
  fs.writeFileSync(tmp, after);
@@ -1203,6 +1245,10 @@ function anchorStampVerb(ctx: RunContext): number {
1203
1245
  baseRef,
1204
1246
  designPath: design?.path ?? null,
1205
1247
  designBaseSha: design?.baseSha ?? null,
1248
+ bkitVersion: bkit?.version ?? null,
1249
+ bkitLatest: bkit?.latest ?? null,
1250
+ bkitOutdated: bkit?.outdated ?? null,
1251
+ bkitAdvisory: bkit?.advisory ?? null,
1206
1252
  changed: before !== after,
1207
1253
  });
1208
1254
  return EXIT.OK;
@@ -1221,7 +1267,7 @@ function anchorReadVerb(ctx: RunContext): number {
1221
1267
  ctx.emit({ ...fields, value: null, skip: reason, landed: null });
1222
1268
  return EXIT_ANCHOR_SKIP;
1223
1269
  };
1224
- const none = { baseSha: null, baseRef: null, designPath: null, designBaseSha: null };
1270
+ const none = Object.fromEntries(ANCHOR_FIELDS.map((f) => [f, null]));
1225
1271
  if (!fs.statSync(file, { throwIfNoEntry: false })?.isFile()) {
1226
1272
  if (against !== undefined) return skip("no-file", `no ${rel} — nothing to check`, none);
1227
1273
  ctx.log(`${rel} not found`);
@@ -1455,7 +1501,7 @@ export const branchesCommand: CommandSpec = {
1455
1501
  },
1456
1502
  "anchor-stamp": {
1457
1503
  summary:
1458
- "Put a <!-- bkit:anchor --> block recording the base commit on top of a design/plan doc or audit report (idempotent).",
1504
+ "Put a <!-- bkit:anchor --> block recording the base commit and bkit release on top of a design/plan doc or audit report (idempotent).",
1459
1505
  flags: [
1460
1506
  { name: "file", type: "string", required: true, help: "doc to stamp (must exist)" },
1461
1507
  {
@@ -1482,6 +1528,12 @@ export const branchesCommand: CommandSpec = {
1482
1528
  designPath: "design path stamped (null when none)",
1483
1529
  designBaseSha:
1484
1530
  "the design doc's baseSha stamped (null when none; empty when it had no anchor)",
1531
+ bkitVersion:
1532
+ "the .bkit/version pin stamped (null when unpinned: no bkit fields are stamped then)",
1533
+ bkitLatest: "newest published bkit stamped (null when unknown: stamped empty)",
1534
+ bkitOutdated:
1535
+ "true when bkitVersion is older than bkitLatest: a visible warning line is stamped under the block (null when unknown)",
1536
+ bkitAdvisory: "one warning line when bkitOutdated, else null",
1485
1537
  changed: "false when the doc already carried exactly this block",
1486
1538
  },
1487
1539
  exitCodes: { [EXIT_NO_FILE]: "--file is missing or not a file" },
@@ -1508,6 +1560,8 @@ export const branchesCommand: CommandSpec = {
1508
1560
  baseRef: "anchor baseRef (null when absent)",
1509
1561
  designPath: "anchor designPath (null when absent)",
1510
1562
  designBaseSha: "anchor designBaseSha (null when absent)",
1563
+ bkitVersion: "anchor bkitVersion (null when absent)",
1564
+ bkitLatest: "anchor bkitLatest (null when absent)",
1511
1565
  value: "the --field value (null when absent or no --field)",
1512
1566
  skip: "with --against: no-file | no-anchor | unreachable | nothing-landed (null = run the check)",
1513
1567
  landed: "with --against: paths changed between baseSha and the ref",
@@ -4,14 +4,15 @@
4
4
  // `owner/repo` comes from `gh repo view`; when gh is missing, unauthed, or
5
5
  // answers nothing, from the `origin` remote URL instead (the MCP fallback the
6
6
  // workflows already describe: "parse git remote"). The current branch, how far it
7
- // trails `origin/dev`, the main checkout, and the bkit binary every later block
8
- // calls ride along so Step 1 is one call.
7
+ // trails `origin/dev`, the main checkout, the bkit binary every later block calls,
8
+ // and whether that bkit is behind the newest release ride along so Step 1 is one call.
9
9
 
10
10
  import * as fs from "node:fs";
11
11
  import * as path from "node:path";
12
12
 
13
13
  import { parseRemoteUrlToSlug } from "../../ledgers/telemetry.js";
14
14
  import { EXIT, git, repoRoot, runGit, runTool, type CommandSpec } from "../lib.js";
15
+ import { bkitVersionStatus } from "../../shared/bkit-latest.js";
15
16
 
16
17
  /** Exit code: neither gh nor the origin remote named an owner/repo. */
17
18
  export const EXIT_NO_REPO = 3;
@@ -122,6 +123,13 @@ export const repoCommand: CommandSpec = {
122
123
  repoRoot: "the main checkout (the same from any worktree)",
123
124
  bkit: "the bkit binary the workflow blocks call: <repoRoot>/node_modules/.bin/bkit, else `bkit` on PATH",
124
125
  outboxRoot: "<git common dir>/bkit-outbox: per-run scratch files, never committed",
126
+ bkitVersion:
127
+ ".bkit/version pinnedVersion: the release this repo's bkit files came from (null when unpinned)",
128
+ bkitLatest:
129
+ "newest published @cbartens/bkit, asked at most once a day (null when offline, opted out via BKIT_NO_UPDATE_CHECK, or unpinned)",
130
+ bkitOutdated:
131
+ "true when bkitVersion is older than bkitLatest (null when either is unknown)",
132
+ bkitAdvisory: "one line to show the user when bkitOutdated, else null",
125
133
  },
126
134
  exitCodes: {
127
135
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -156,6 +164,8 @@ export const repoCommand: CommandSpec = {
156
164
  }
157
165
  const root = repoRoot(ctx.cwd);
158
166
  const common = git(ctx.cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
167
+ const latest = bkitVersionStatus(root, common);
168
+ if (latest.advisory !== null) ctx.log(latest.advisory);
159
169
  ctx.emit({
160
170
  ...resolved,
161
171
  owner,
@@ -165,6 +175,10 @@ export const repoCommand: CommandSpec = {
165
175
  repoRoot: root,
166
176
  bkit: resolveBkitBinary(root),
167
177
  outboxRoot: path.join(common ?? path.join(root, ".git"), "bkit-outbox"),
178
+ bkitVersion: latest.version,
179
+ bkitLatest: latest.latest,
180
+ bkitOutdated: latest.outdated,
181
+ bkitAdvisory: latest.advisory,
168
182
  });
169
183
  if (branch === null && ctx.flags.allowDetached !== true) {
170
184
  ctx.log("HEAD is detached — no current branch");
@@ -55,7 +55,7 @@ import {
55
55
  type FlagValue,
56
56
  type RunContext,
57
57
  } from "../lib.js";
58
- import { pushBranch, readAnchor, stampAnchor } from "./branches.js";
58
+ import { anchorBkitStatus, pushBranch, readAnchor, stampAnchor } from "./branches.js";
59
59
  import {
60
60
  AUTO_LABEL,
61
61
  AUTO_ROUTE_SUFFIX,
@@ -998,7 +998,7 @@ export function highestVersion(dir: string, workflow: string): { file: string; n
998
998
  return best;
999
999
  }
1000
1000
 
1001
- /** Stamp `file`'s anchor when a base commit is known (plan: with its design's own anchor). */
1001
+ /** Stamp `file`'s anchor when a base commit is known (plan: with its design's own anchor; both: the bkit release). */
1002
1002
  function stamp(cwd: string, file: string, baseSha: string, design?: string): void {
1003
1003
  if (baseSha === "") return;
1004
1004
  const abs = path.resolve(cwd, file);
@@ -1008,7 +1008,8 @@ function stamp(cwd: string, file: string, baseSha: string, design?: string): voi
1008
1008
  ? { path: design, baseSha: readAnchor(fs.readFileSync(designAbs, "utf-8")).baseSha ?? "" }
1009
1009
  : undefined;
1010
1010
  const tmp = `${abs}.bkit-anchor.tmp`;
1011
- fs.writeFileSync(tmp, stampAnchor(fs.readFileSync(abs, "utf-8"), baseSha, d));
1011
+ const text = fs.readFileSync(abs, "utf-8");
1012
+ fs.writeFileSync(tmp, stampAnchor(text, baseSha, d, undefined, anchorBkitStatus(cwd)));
1012
1013
  fs.renameSync(tmp, abs);
1013
1014
  }
1014
1015