@cbartens/bkit 6.0.0 → 6.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +154 -151
- package/.bkit/core/.agents/context.md +95 -29
- package/.bkit/core/.agents/docs.md +17 -15
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
- package/.bkit/core/.agents/rules.md +108 -107
- package/.bkit/core/.agents/skills.md +63 -15
- package/.bkit/core/.bkit/README.md +154 -151
- package/.bkit/core/.bkit/authoring.md +714 -84
- package/.bkit/core/.bkit/cli.md +407 -0
- package/.bkit/core/.bkit/cloud.md +281 -193
- package/.bkit/core/.bkit/comparison.md +43 -41
- package/.bkit/core/.bkit/install.md +154 -84
- package/.bkit/core/.bkit/jsonl.md +193 -130
- package/.bkit/core/.bkit/pipeline.md +114 -114
- package/.bkit/core/.bkit/prompts.md +272 -165
- package/.bkit/core/.bkit/providers.md +457 -271
- package/.bkit/core/.bkit/router.md +69 -0
- package/.bkit/core/.bkit/templates.md +529 -256
- package/.bkit/core/.bkit/trackers.md +80 -52
- package/.bkit/core/.bkit/workflows.md +589 -504
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
- package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
- package/.bkit/core/AGENTS.md +5 -73
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
- package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
- package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
- package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
- package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
- package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
- package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
- package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
- package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
- package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
- package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
- package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
- package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
- package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
- package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
- package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
- package/.bkit/core/docs/templates/bkit-plan.md +138 -132
- package/.bkit/core/engine/checks/after/auth.ts +40 -37
- package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
- package/.bkit/core/engine/checks/after/index.ts +12 -2
- package/.bkit/core/engine/checks/after/tools.ts +80 -33
- package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
- package/.bkit/core/engine/checks/before/env.ts +1 -1
- package/.bkit/core/engine/checks/before/index.ts +7 -0
- package/.bkit/core/engine/checks/before/repo.ts +40 -0
- package/.bkit/core/engine/checks/status-holes.ts +916 -123
- package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
- package/.bkit/core/engine/checks/tips/detect.ts +32 -0
- package/.bkit/core/engine/checks/tips/index.ts +47 -6
- package/.bkit/core/engine/cli.ts +238 -84
- package/.bkit/core/engine/commands/analysis.ts +128 -76
- package/.bkit/core/engine/commands/ci/ci.ts +363 -29
- package/.bkit/core/engine/commands/ci/pins.ts +172 -0
- package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
- package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
- package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
- package/.bkit/core/engine/commands/land.ts +126 -11
- package/.bkit/core/engine/commands/lib.ts +303 -6
- package/.bkit/core/engine/commands/registry.ts +6 -2
- package/.bkit/core/engine/commands/setup/setup.ts +1 -0
- package/.bkit/core/engine/commands/stats.ts +91 -35
- package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
- package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
- package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
- package/.bkit/core/engine/commands/workflow/context.ts +433 -55
- package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
- package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
- package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
- package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
- package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
- package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
- package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
- package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
- package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
- package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
- package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
- package/.bkit/core/engine/commands/workflow/status.ts +200 -17
- package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
- package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
- package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
- package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
- package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
- package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
- package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
- package/.bkit/core/engine/install/cloud-env.ts +251 -121
- package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
- package/.bkit/core/engine/install/manifest.ts +60 -12
- package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
- package/.bkit/core/engine/install/modules/cloud.ts +3 -3
- package/.bkit/core/engine/install/modules/codex.ts +15 -2
- package/.bkit/core/engine/install/modules/core.ts +956 -52
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/opencode.ts +16 -4
- package/.bkit/core/engine/install/template-notes.ts +130 -0
- package/.bkit/core/engine/install/version-file.ts +3 -2
- package/.bkit/core/engine/install/write.ts +5 -0
- package/.bkit/core/engine/ledgers/compact.ts +124 -0
- package/.bkit/core/engine/ledgers/journal.ts +291 -0
- package/.bkit/core/engine/ledgers/status.ts +160 -9
- package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
- package/.bkit/core/engine/render/hosts.ts +114 -14
- package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
- package/.bkit/core/engine/shared/dep-updater.ts +60 -0
- package/.bkit/core/engine/shared/egress.ts +1 -1
- package/.bkit/core/engine/shared/package-manager.ts +9 -0
- package/.bkit/core/engine/shared/settings.ts +92 -17
- package/.bkit/core/engine/shared/timeouts.ts +2 -0
- package/.bkit/core/engine/tools/cli-doc.ts +111 -0
- package/.bkit/core/engine/tools/grammar-density.ts +1 -1
- package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
- package/.bkit/core/engine/tools/instructions.ts +94 -43
- package/.bkit/core/hooks/antigravity-hook.js +25 -10
- package/.bkit/core/hooks/gateguard-engine.js +53 -29
- package/.bkit/core/hooks/guardrails-shell.js +4 -4
- package/.bkit/core/hooks/guardrails-tiers.js +3 -3
- package/.bkit/core/hooks/preflight-linear.sh +9 -9
- package/.bkit/core/hooks/preflight-rules.sh +8 -0
- package/.bkit/core/hooks/readguard-engine.js +29 -10
- package/.bkit/core/hooks/session-rules-advisory.js +61 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
- package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
- package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
- package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
- package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
- package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
- package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
- package/.bkit/core/prompts/bkit-design-generate.md +68 -52
- package/.bkit/core/prompts/bkit-design-organise.md +73 -35
- package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
- package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
- package/.bkit/core/prompts/bkit-design-spike.md +54 -47
- package/.bkit/core/prompts/bkit-design-update.md +42 -31
- package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
- package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
- package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
- package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
- package/.bkit/core/prompts/bkit-plan-update.md +70 -52
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
- package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
- package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
- package/.bkit/core/workflows/bkit-auto.md +53 -30
- package/.bkit/core/workflows/bkit-build.md +635 -304
- package/.bkit/core/workflows/bkit-debug.md +301 -148
- package/.bkit/core/workflows/bkit-design.md +167 -95
- package/.bkit/core/workflows/bkit-plan.md +172 -84
- package/.bkit/core/workflows/bkit-ship.md +299 -152
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
- package/.bkit/shared/.claude/bkit-cloud.md +12 -10
- package/.bkit/shared/.claude/settings.json +3 -0
- package/.bkit/shared/.codex/bkit-cloud.md +98 -0
- package/.bkit/shared/.codex/hooks.json +20 -0
- package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
- package/.bkit/shared/.opencode/opencode.json +1 -1
- package/.bkit/shared/CLAUDE.md +5 -1
- package/.bkit/shared/GEMINI.md +4 -1
- package/.bkit/shared/docs/architecture.md +4 -7
- package/.bkit/shared/docs/data-schema.md +4 -7
- package/.bkit/shared/docs/deployments.md +239 -166
- package/.bkit/shared/docs/design.md +11 -12
- package/.bkit/shared/docs/noise.md +8 -7
- package/.bkit/shared/docs/observability.md +5 -8
- package/.bkit/shared/docs/security.md +35 -17
- package/.bkit/shared/docs/setup.md +29 -18
- package/.bkit/shared/docs/technology.md +3 -6
- package/.bkit/shared/docs/testing.md +282 -176
- package/.bkit/shared/gitignore +6 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
- package/.bkit/templates/.cursor/Dockerfile +12 -8
- package/.bkit/templates/.cursor/environment.json +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
- package/.bkit/templates/.github/renovate.json5 +34 -6
- package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
- package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
- package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
- package/.bkit/templates/.husky/pre-commit +2 -2
- package/.bkit/templates/.husky/pre-push +95 -35
- package/.bkit/templates/.prettierignore +6 -7
- package/.bkit/templates/.vale.ini +27 -27
- package/.bkit/templates/context/bkit-cloudrun.md +23 -15
- package/.bkit/templates/context/bkit-expo.md +70 -52
- package/.bkit/templates/context/bkit-github.md +93 -56
- package/.bkit/templates/context/bkit-inngest.md +21 -15
- package/.bkit/templates/context/bkit-maestro.md +22 -16
- package/.bkit/templates/context/bkit-playwright.md +23 -17
- package/.bkit/templates/context/bkit-resend.md +12 -10
- package/.bkit/templates/context/bkit-sentry.md +30 -20
- package/.bkit/templates/context/bkit-serena.md +8 -7
- package/.bkit/templates/context/bkit-stripe.md +14 -13
- package/.bkit/templates/context/bkit-supabase.md +16 -13
- package/.bkit/templates/context/bkit-tavily.md +14 -11
- package/.bkit/templates/context/bkit-vercel.md +27 -18
- package/.bkit/templates/docs/capabilities.md +15 -14
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
- package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
- package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
- package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
- package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
- package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
- package/.bkit/templates/slop-scan.config.json +9 -2
- package/CHANGELOG.md +119 -0
- package/README.md +250 -76
- package/dist/checks/after/auth.js +36 -33
- package/dist/checks/after/ci-yml.js +52 -2
- package/dist/checks/after/index.js +12 -4
- package/dist/checks/after/tools.js +73 -33
- package/dist/checks/before/context-fetch.js +218 -33
- package/dist/checks/before/env.js +1 -1
- package/dist/checks/before/index.js +6 -2
- package/dist/checks/before/repo.js +35 -1
- package/dist/checks/status-holes.js +739 -114
- package/dist/checks/tips/catalogue.js +59 -17
- package/dist/checks/tips/detect.js +30 -0
- package/dist/checks/tips/index.js +48 -6
- package/dist/cli.js +222 -84
- package/dist/commands/analysis.js +77 -53
- package/dist/commands/ci/ci.js +302 -25
- package/dist/commands/ci/pins.js +142 -0
- package/dist/commands/ci/push-gate.js +194 -0
- package/dist/commands/install/uninstall.js +23 -27
- package/dist/commands/install/upgrade.js +21 -11
- package/dist/commands/land.js +126 -10
- package/dist/commands/lib.js +244 -5
- package/dist/commands/registry.js +6 -2
- package/dist/commands/setup/setup.js +1 -0
- package/dist/commands/stats.js +69 -30
- package/dist/commands/workflow/branches.js +1232 -111
- package/dist/commands/workflow/challenge.js +90 -37
- package/dist/commands/workflow/completeness.js +97 -0
- package/dist/commands/workflow/context.js +371 -51
- package/dist/commands/workflow/counters.js +206 -40
- package/dist/commands/workflow/decisions.js +60 -17
- package/dist/commands/workflow/disk.js +213 -55
- package/dist/commands/workflow/fids.js +18 -1
- package/dist/commands/workflow/issues.js +6 -0
- package/dist/commands/workflow/ledgers.js +372 -21
- package/dist/commands/workflow/locks.js +2 -0
- package/dist/commands/workflow/plan-blocks.js +78 -14
- package/dist/commands/workflow/plans.js +205 -0
- package/dist/commands/workflow/prs.js +12 -3
- package/dist/commands/workflow/repo.js +6 -0
- package/dist/commands/workflow/roadmap.js +50 -17
- package/dist/commands/workflow/run-facts.js +23 -28
- package/dist/commands/workflow/runs.js +530 -33
- package/dist/commands/workflow/runtime.js +3 -0
- package/dist/commands/workflow/skills.js +1 -0
- package/dist/commands/workflow/status.js +166 -19
- package/dist/commands/workflow/step-table.js +61 -29
- package/dist/commands/workflow/steps.js +542 -26
- package/dist/commands/workflow/summary-findings.js +117 -0
- package/dist/commands/workflow/summary.js +154 -41
- package/dist/commands/workflow/tasks.js +378 -0
- package/dist/commands/workflow/test-blocks.js +231 -0
- package/dist/commands/workflow/tests-changed.js +172 -0
- package/dist/commands/workflow/tests.js +1013 -321
- package/dist/commands/workflow/workflows.js +191 -38
- package/dist/commands/workflow/worktrees.js +310 -42
- package/dist/install/cloud-env.js +233 -99
- package/dist/install/context-ci-workflow.js +85 -0
- package/dist/install/manifest.js +57 -12
- package/dist/install/modules/antigravity.js +3 -2
- package/dist/install/modules/cloud.js +3 -3
- package/dist/install/modules/codex.js +12 -2
- package/dist/install/modules/core.js +851 -53
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/opencode.js +11 -5
- package/dist/install/template-notes.js +116 -0
- package/dist/install/version-file.js +3 -2
- package/dist/ledgers/compact.js +87 -0
- package/dist/ledgers/journal.js +233 -0
- package/dist/ledgers/status.js +115 -5
- package/dist/ledgers/telemetry.js +121 -17
- package/dist/render/hosts.js +100 -14
- package/dist/shared/bkit-latest.js +26 -4
- package/dist/shared/dep-updater.js +49 -0
- package/dist/shared/egress.js +1 -1
- package/dist/shared/package-manager.js +6 -0
- package/dist/shared/settings.js +59 -10
- package/dist/shared/timeouts.js +2 -0
- package/dist/tools/cli-doc.js +97 -0
- package/dist/tools/grammar-density.js +1 -1
- package/dist/tools/instructions-sources.js +15 -16
- package/dist/tools/instructions.js +83 -39
- package/package.json +58 -42
- package/.bkit/core/.bkit/lite.md +0 -73
- package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
- package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
- package/dist/commands/workflow/workstreams.js +0 -149
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
- /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
- /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
|
@@ -2,23 +2,30 @@
|
|
|
2
2
|
|
|
3
3
|
{{BKIT_MANAGED_MARKER}}
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
> [!CAUTION]
|
|
6
|
+
> **Purpose:** This file covers first-time install and upgrade, the install lifecycle, uninstall and recovery. It ships in the package at `node_modules/@cbartens/bkit/.bkit/core/.bkit/install.md` and is mirrored into the consumer repo at `.bkit/install.md`. Ongoing ops and triggering workflows are in `.bkit/README.md`.
|
|
7
|
+
>
|
|
8
|
+
> **Rules:**
|
|
9
|
+
>
|
|
10
|
+
> - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit this file.
|
|
11
|
+
> - This file ships to every project that installs bkit. Describe the current setup only.
|
|
12
|
+
> - Leave out internal labels, such as tracker issue numbers, ledger keys and review-finding ids, and leave out project history. Decisions go in `docs/decisions.jsonl`, and incidents go in `docs/knowledge.jsonl`.
|
|
6
13
|
|
|
7
14
|
> [!IMPORTANT]
|
|
8
|
-
> **bkit installs from npmjs.** `@cbartens/bkit` is public on `https://registry.npmjs.org
|
|
15
|
+
> **bkit installs from npmjs.** `@cbartens/bkit` is public on `https://registry.npmjs.org`, so `pnpm add -D @cbartens/bkit` resolves with no registry mapping, PAT, or CI / Vercel env.
|
|
9
16
|
|
|
10
17
|
## Quick install / upgrade — paste into your AI
|
|
11
18
|
|
|
12
|
-
|
|
19
|
+
There are two paste blocks below: install (first time) and upgrade (already on bkit). Both end the same way: apply advisories, reconcile templates, and verify with `bkit check`.
|
|
13
20
|
|
|
14
21
|
### Install — first time
|
|
15
22
|
|
|
16
|
-
No token or registry setup is needed
|
|
23
|
+
No token or registry setup is needed, because `@cbartens/bkit` is public on npmjs. Copy the block below into Claude / Codex / Antigravity / Cursor / OpenCode.
|
|
17
24
|
|
|
18
25
|
````text
|
|
19
26
|
Install the latest `@cbartens/bkit` in this repo and finish setup.
|
|
20
27
|
1. `@cbartens/bkit` is public on npmjs — no registry mapping, no PAT, no env. Confirmed.
|
|
21
|
-
2. Install and seed hosts in one Bash call (`bkit install` requires named modules — core implicit; pick the hosts this repo uses from `--claude --
|
|
28
|
+
2. Install and seed hosts in one Bash call (`bkit install` requires named modules — core implicit; pick the hosts this repo uses from `--claude --codex --antigravity --cursor --opencode=<provider>`, provider = `openrouter` | `ollama` | `opencode-zen` | `opencode-go`; if `bkit` not on PATH use `pnpm bkit`):
|
|
22
29
|
```bash
|
|
23
30
|
pnpm add -D @cbartens/bkit@latest && \
|
|
24
31
|
bkit install --claude --cursor
|
|
@@ -26,12 +33,13 @@ Install the latest `@cbartens/bkit` in this repo and finish setup.
|
|
|
26
33
|
Writes `.agents/`, `.claude/`, `.cursor/` and the `bkit:gate:*` `package.json` scripts, and copies the templates (CI workflow, hooks, tool configs) into `.bkit/templates/` without applying them. `.bkit/templates.md` lists each template plus the tool scripts and devDeps the gates chain.
|
|
27
34
|
3. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why. Then § Setup tips: follow each tip's **Agent steps** unless the person declines it.
|
|
28
35
|
4. Read `.bkit/templates.md`, then compare each template in `.bkit/templates/` (CI workflows, git hooks, lint and Vale configs, Cursor config, dependency updaters, etc.) with this repo. bkit never applies templates, so adoption is your job: adopt unless adoption would break existing functionality. For any template not adopted, state which and why.
|
|
29
|
-
5.
|
|
36
|
+
5. Reconcile every permanent skill through `.agents/skills.md` § Install / Update, including the project's own rows. Verify each skill file and installer-generated lock entry, and review its activation boundaries.
|
|
37
|
+
6. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons), skills reconciled or incomplete (with errors).
|
|
30
38
|
````
|
|
31
39
|
|
|
32
40
|
### Upgrade — already installed
|
|
33
41
|
|
|
34
|
-
|
|
42
|
+
Copy this block when the repo already has `@cbartens/bkit`. Prefer `bkit upgrade --latest`, which bumps the package and resyncs the managed files. Do not run only `pnpm add`.
|
|
35
43
|
|
|
36
44
|
````text
|
|
37
45
|
Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resync.
|
|
@@ -42,12 +50,13 @@ Upgrade `@cbartens/bkit` to the latest version in this repo and finish the resyn
|
|
|
42
50
|
Do **not** only `pnpm add @cbartens/bkit@latest` — that refreshes the package without resyncing managed files.
|
|
43
51
|
2. Read `.bkit/advisories.md` end-to-end. For every `[advisory]`/`[blocker]`: apply its **Action** unless truly N/A. If you skip, state advisory id and why. Then § Setup tips: follow each tip's **Agent steps** unless the person declines it.
|
|
44
52
|
3. Read the template changes `bkit upgrade` printed (or `git diff .bkit/templates`), then `.bkit/templates.md`. bkit never applies templates, so adoption is your job: adopt each change unless it would break existing functionality. For any change not adopted, state which and why.
|
|
45
|
-
4.
|
|
53
|
+
4. Reconcile every permanent skill through `.agents/skills.md` § Install / Update, including the project's own rows. Verify each skill file and installer-generated lock entry, and review its activation boundaries.
|
|
54
|
+
5. Re-run `bkit check` (or `pnpm bkit check`). Fix remaining drift/advisories you can. End with: resolved version, advisories applied, advisories skipped (with reasons), templates adopted/skipped (with reasons), skills reconciled or incomplete (with errors).
|
|
46
55
|
````
|
|
47
56
|
|
|
48
57
|
## Install
|
|
49
58
|
|
|
50
|
-
bkit is published publicly on
|
|
59
|
+
bkit is published publicly on npmjs (`https://registry.npmjs.org`). Add it to a consumer repo:
|
|
51
60
|
|
|
52
61
|
```bash
|
|
53
62
|
pnpm add -D @cbartens/bkit
|
|
@@ -63,13 +72,14 @@ Run these in order on a brand-new consumer repo.
|
|
|
63
72
|
| 1 | `pnpm add -D @cbartens/bkit` — no token, no registry mapping | this section |
|
|
64
73
|
| 2 | Run `bkit install --claude --cursor` to seed both hosts (writes `.bkit/.env.example`; `.envrc` is a template in `.bkit/templates/`) | this section |
|
|
65
74
|
| 3 | Set up direnv + `.bkit/.env` for `BKIT_GH_TOKEN` (GitHub MCP), `BKIT_LINEAR_API_KEY` or `BKIT_JIRA_API_KEY` — no registry token | [§ Local env setup](#local-env-setup) |
|
|
66
|
-
| 4 |
|
|
75
|
+
| 4 | Reconcile permanent third-party skills and their lock entries | `.agents/skills.md` § Install / Update |
|
|
76
|
+
| 5 | Push to a feature branch and verify CI runs green | — |
|
|
67
77
|
|
|
68
|
-
No CI step, secret, `.npmrc` mapping or Vercel env is needed
|
|
78
|
+
No CI step, secret, `.npmrc` mapping or Vercel env is needed, because CI reaches npmjs anonymously.
|
|
69
79
|
|
|
70
80
|
### Then in the consumer repo
|
|
71
81
|
|
|
72
|
-
`bkit install` requires you to name
|
|
82
|
+
`bkit install` requires you to name at least one module, and a bare `bkit install` errors. Core (the stack-agnostic foundation) is always implicit. Re-run it, or run `bkit upgrade`, after package updates. Use `bkit check` as the CI drift gate.
|
|
73
83
|
|
|
74
84
|
> **Shell alias (add once to `~/.zshrc` or `~/.bashrc`, then `source ~/.zshrc`)**
|
|
75
85
|
>
|
|
@@ -77,19 +87,19 @@ No CI step, secret, `.npmrc` mapping or Vercel env is needed — CI reaches npmj
|
|
|
77
87
|
> alias bkit='pnpm bkit'
|
|
78
88
|
> ```
|
|
79
89
|
>
|
|
80
|
-
> Type `bkit <verb>` from anywhere in repo. Without alias, prefix with `pnpm`: `pnpm bkit install --claude`. `bkit doctor` emits advisory if
|
|
90
|
+
> Type `bkit <verb>` from anywhere in the repo. Without the alias, prefix with `pnpm`: `pnpm bkit install --claude`. `bkit doctor` emits an advisory if it does not detect the alias.
|
|
81
91
|
|
|
82
92
|
```bash
|
|
83
93
|
# Name the host(s) + stack you want — core is implicit. Hosts compose.
|
|
84
94
|
bkit install --claude # .claude/** + CLAUDE.md + core
|
|
85
|
-
bkit install --cursor # .cursor/** + core
|
|
86
95
|
bkit install --codex # Codex CLI host + core
|
|
87
|
-
bkit install --antigravity #
|
|
88
|
-
bkit install --
|
|
89
|
-
|
|
96
|
+
bkit install --antigravity # Antigravity host + core
|
|
97
|
+
bkit install --cursor # .cursor/** + core
|
|
98
|
+
bkit install --opencode=opencode-go # additive OpenCode host (OpenCode-native gateway) + core
|
|
99
|
+
# OpenCode provider: openrouter | ollama | opencode-zen | opencode-go
|
|
90
100
|
|
|
91
101
|
# A bare install errors — name at least one module, or a tracker:
|
|
92
|
-
bkit install # ✗ error: requires
|
|
102
|
+
bkit install # ✗ error: requires >=1 module flag
|
|
93
103
|
bkit install --tracker=github # tracker alone: re-renders every installed host
|
|
94
104
|
|
|
95
105
|
# Ongoing sync — re-render everything installed at the CURRENT version (offline)
|
|
@@ -102,24 +112,27 @@ bkit upgrade --latest # newest published; or --to=<version> t
|
|
|
102
112
|
bkit check
|
|
103
113
|
```
|
|
104
114
|
|
|
105
|
-
**Module flags** (composable;
|
|
115
|
+
**Module flags** (composable; install and uninstall are symmetric): `--claude` `--codex` `--antigravity` `--cursor` `--opencode=<provider>`. Any other module flag is an unknown-flag error.
|
|
116
|
+
|
|
117
|
+
- The CI workflow, the Vale config, the tool configs, the git hooks, the slop-scan type-suppression plugin (`scripts/slop/bkit-slop-type-suppression.mjs`), and the tool `package.json` scripts and devDeps are templates you copy from `.bkit/templates/` (`.bkit/templates.md`).
|
|
118
|
+
- Core, implicit on every install, seeds the `bkit:gate:*` / `bkit:deps:*` scripts every workflow runs. It adds them only if missing, and never touches a name that is already present. Point their values at your stack (see `.bkit/README.md` § Required tools).
|
|
106
119
|
|
|
107
|
-
**Opt-in flags:** `--tracker=github|linear|jira`, `--auto=claude|cursor|opencode` (cloud agents), `--opencode=<provider>` (additive
|
|
120
|
+
**Opt-in flags:** `--tracker=github|linear|jira`, `--auto=claude|cursor|opencode` (cloud agents), `--opencode=<provider>` (additive OpenCode execution host: `openrouter`, `ollama`, `opencode-zen`, `opencode-go`). For dependency updaters, copy an example and own it. See [§ Optional post-install decisions](#optional-post-install-decisions).
|
|
108
121
|
|
|
109
122
|
### Payload view links — `.bkit/core` + `.bkit/shared`
|
|
110
123
|
|
|
111
|
-
Install and upgrade create two
|
|
124
|
+
Install and upgrade create two relative symlinks into the installed package, so the payload sources (workflows, prompts, hooks) can be browsed in the repo: `.bkit/core` → `../node_modules/@cbartens/bkit/.bkit/core`, and the same shape for `shared`. They are views, not copies, so they always show the installed version with zero drift. Rules:
|
|
112
125
|
|
|
113
|
-
- Both paths sit in the `.gitignore` managed block
|
|
114
|
-
- The `bkit` binary reads its payload from the package regardless
|
|
115
|
-
- A real directory at either path is never clobbered (advisory `payload-link-real-dir`)
|
|
116
|
-
- `bkit uninstall` removes the links
|
|
126
|
+
- Both paths sit in the `.gitignore` managed block. They dangle on a fresh clone or in CI (no `node_modules`), and `bkit install` / `upgrade` recreates them. A missing or mis-pointed link is never `bkit check` drift, because links join no WriteSet.
|
|
127
|
+
- The `bkit` binary reads its payload from the package regardless, so the links are browse-only. Editors resolve them to the `node_modules/…` paths.
|
|
128
|
+
- A real directory at either path is never clobbered (advisory `payload-link-real-dir`). Remove it yourself and re-run install to get the link. A platform that refuses symlinks (Windows without Developer Mode) falls back to a junction, then to advisory `payload-link-failed`, and never fails.
|
|
129
|
+
- `bkit uninstall` removes the links. It removes symlinks only, and consumer content stays.
|
|
117
130
|
|
|
118
|
-
>
|
|
131
|
+
> **Moving bkit versions: use `bkit upgrade --latest` (or `--to=<version>`).** It bumps `@cbartens/bkit` and resyncs the `.agents/` payload + `.bkit/version` pin in one atomic step, so the two can never drift apart. A bare `pnpm add @cbartens/bkit` (or a Renovate / Dependabot bump) only refreshes `package.json` + the lockfile and does not resync. Skipping the resync reds CI on the `bkit check` drift gate. If you bump the package separately, run `bkit upgrade` afterward and commit the resync alongside the version bump in the same PR. A target equal to the installed version re-renders in place. The exception is when `package.json` declares `@cbartens/bkit` by a non-registry spec (`file:` tarball, `link:`, `workspace:`, `npm:` alias, git, URL, path): then it still runs `pnpm add` to swap in the published package.
|
|
119
132
|
|
|
120
133
|
### Local env setup
|
|
121
134
|
|
|
122
|
-
|
|
135
|
+
There are two flows. Pick one. Both put `BKIT_GH_TOKEN` in the shell for the GitHub MCP server. Linear repos also need `BKIT_LINEAR_API_KEY`, and Jira repos need `BKIT_JIRA_API_KEY` (`.bkit/trackers.md` § jira — setup and notes). Use `gh auth login` for the CLI.
|
|
123
136
|
|
|
124
137
|
#### Flow A — Shell export (quickest, no extra deps)
|
|
125
138
|
|
|
@@ -133,11 +146,11 @@ export BKIT_JIRA_API_KEY=<Atlassian MCP V2 scoped token> # Jira MCP
|
|
|
133
146
|
source ~/.zshrc # or: source ~/.bashrc
|
|
134
147
|
```
|
|
135
148
|
|
|
136
|
-
Pros: one step, no install. Cons: tokens in every shell on machine
|
|
149
|
+
Pros: one step, no install. Cons: the tokens are in every shell on the machine, with no per-repo scoping.
|
|
137
150
|
|
|
138
151
|
#### Flow B — direnv + `.bkit/.env` (recommended for daily use)
|
|
139
152
|
|
|
140
|
-
`bkit install` writes `.bkit/.env.example` (placeholders + permission notes
|
|
153
|
+
`bkit install` writes `.bkit/.env.example` (placeholders + permission notes). bkit owns that file and overwrites edits, so real values go in `.bkit/.env`. `.envrc` (`dotenv_if_exists .bkit/.env`) is a template: copy it from `.bkit/templates/.envrc`. direnv loads `.bkit/.env` on `cd` and unloads it when you leave, so the tokens are scoped to the repo.
|
|
141
154
|
|
|
142
155
|
```bash
|
|
143
156
|
# 1. One-time per machine — install direnv
|
|
@@ -159,21 +172,34 @@ echo "len=${#BKIT_GH_TOKEN}" # non-ze
|
|
|
159
172
|
gh auth status # gh CLI uses keyring, not BKIT_GH_TOKEN
|
|
160
173
|
```
|
|
161
174
|
|
|
162
|
-
After step 4, restart open Claude
|
|
175
|
+
After step 4, restart any open Claude / Cursor sessions in this repo, so the new env reaches the MCP servers.
|
|
163
176
|
|
|
164
|
-
`.bkit/.env` gitignored
|
|
177
|
+
`.bkit/.env` is gitignored. NEVER commit it. For cloud sessions (Claude on the web, Cursor Background Agents), set the same names in each host's online dashboard (see `.bkit/cloud.md` § Tokens by session type). `bkit install` / `bkit check` advisories detect a missing direnv, blank required keys and an un-allowed `.envrc`. Follow whichever fires.
|
|
165
178
|
|
|
166
|
-
## Cloud agent environments (Claude
|
|
179
|
+
## Cloud agent environments (Claude on the web + Cursor Background Agents)
|
|
167
180
|
|
|
168
|
-
bkit ships repo-side scaffolding for both cloud agents
|
|
181
|
+
bkit ships repo-side scaffolding for both cloud agents:
|
|
169
182
|
|
|
170
|
-
|
|
183
|
+
- The opt-in `bkit install --auto=claude` writes no file.
|
|
184
|
+
- The per-session install hook (`.claude/hooks/bkit-cloud-bootstrap.sh`), the phase-routed `.github/workflows/bkit-cloud.yml` and the Cursor cloud image files (`.cursor/Dockerfile`, `.cursor/environment.json`) are templates in `.bkit/templates/` that you copy and own.
|
|
185
|
+
- `.cursor/hooks.json` (the Linear preflight wiring) ships with `--cursor`, not `--auto`.
|
|
186
|
+
- An install without `--auto` ships zero cloud footprint.
|
|
171
187
|
|
|
172
|
-
|
|
188
|
+
You configure the online-dashboard half (the Claude env in `claude.ai/code`, the Cursor env vars in `Cursor → Settings → Background Agents`) once per machine / account.
|
|
189
|
+
|
|
190
|
+
For post-CI auto-routing (ship-vs-debug after CI), bkit ships a single `.github/workflows/bkit-cloud.yml` template with two runtime-gated dispatch jobs, plus a `/bkit-auto` slash command that both clouds invoke from a single source:
|
|
191
|
+
|
|
192
|
+
- The **claude** job (`claude-code-action`) runs when the `ANTHROPIC_API_KEY` repo secret is set, or keyless through the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables.
|
|
193
|
+
- The **OpenCode** job (`opencode run` CLI) runs when `OPENCODE_PROVIDER_KEY` is set.
|
|
194
|
+
- Cursor wires the slash command through a dashboard trigger, with no GHA on the Cursor side.
|
|
195
|
+
|
|
196
|
+
`bkit install --auto=opencode` requires `tracker=github`.
|
|
197
|
+
|
|
198
|
+
`.bkit/cloud.md` holds the full recipe, the paste-in setup script, the env-var inventory, the Cursor dashboard config and the consumer customisation patterns. The host-delta matrix is in `.bkit/providers.md` § Runtime environment.
|
|
173
199
|
|
|
174
200
|
## JSON ownership model — deep-containment
|
|
175
201
|
|
|
176
|
-
`.claude/settings.json` and `.cursor/hooks.json` managed
|
|
202
|
+
`.claude/settings.json` and `.cursor/hooks.json` are managed through **deep-containment**: bkit declares a scope (the full template JSON tree) that must be present as a subset of the consumer's document. Consumer-added keys outside the template tree survive every `bkit install` byte-identically, with no special key or wrapper required.
|
|
177
203
|
|
|
178
204
|
```json
|
|
179
205
|
// .claude/settings.json
|
|
@@ -188,13 +214,13 @@ Full recipe + paste-in setup script + env-var inventory + Cursor dashboard confi
|
|
|
188
214
|
}
|
|
189
215
|
```
|
|
190
216
|
|
|
191
|
-
In this example, `hooks.SessionStart` is bkit-declared scope (from template). `hooks.Stop` and `failClosed` are consumer-added
|
|
217
|
+
In this example, `hooks.SessionStart` is bkit-declared scope (from the template). `hooks.Stop` and `failClosed` are consumer-added, and bkit never touches them.
|
|
192
218
|
|
|
193
219
|
**Rules:**
|
|
194
220
|
|
|
195
|
-
- Consumer keys outside template tree survive every `bkit install` byte-identically.
|
|
196
|
-
- `bkit install` uses `deepContains(template, consumer)
|
|
197
|
-
- `bkit check` surfaces `tier2-json-drift` advisory when `deepContains` fails and
|
|
221
|
+
- Consumer keys outside the template tree survive every `bkit install` byte-identically.
|
|
222
|
+
- `bkit install` uses `deepContains(template, consumer)`, which checks that every template leaf is present. On drift, it deep-merges with the template winning, and consumer-only siblings are preserved.
|
|
223
|
+
- `bkit check` surfaces the `tier2-json-drift` advisory when `deepContains` fails, and exits 1 (CI drift gate). It writes nothing. The consumer reviews and re-runs `bkit install` to reconverge.
|
|
198
224
|
- `.cursor/hooks.json` uses Cursor v1 keyed-object schema: `{"version": 1, "hooks": {"sessionStart": [...], "sessionStop": [...]}}`.
|
|
199
225
|
|
|
200
226
|
## Install lifecycle
|
|
@@ -203,7 +229,7 @@ In this example, `hooks.SessionStart` is bkit-declared scope (from template). `h
|
|
|
203
229
|
|
|
204
230
|
**Phase 1 — Preflight (read-only, before any writes)**
|
|
205
231
|
|
|
206
|
-
bkit checks preconditions and known advisory patterns before touching any file.
|
|
232
|
+
bkit checks preconditions and known advisory patterns before touching any file. When a blocker fires, install exits 1 immediately with a formatted `[blocker]` line and zero writes. Advisories are collected for Phase 3.
|
|
207
233
|
|
|
208
234
|
<!-- prettier-ignore -->
|
|
209
235
|
| Severity | When |
|
|
@@ -219,35 +245,60 @@ Module dispatch writes managed files.
|
|
|
219
245
|
|
|
220
246
|
**Phase 3 — Post-install (re-detect + unified output)**
|
|
221
247
|
|
|
222
|
-
After writes, bkit re-runs credential and environment checks
|
|
248
|
+
After the writes, bkit re-runs the credential and environment checks, because some are only accurate after install (for example the `bkit:gate:*` scripts core just seeded into `package.json`). The table also lists the module advisories that render in the same checklist.
|
|
223
249
|
|
|
224
250
|
<!-- prettier-ignore -->
|
|
225
251
|
| `id` | When |
|
|
226
252
|
| --- | --- |
|
|
227
253
|
| `bkit-managed-duplicate` | A managed markdown file holds an older unmarked copy of its block outside `bkit:start`/`bkit:end`: the block's `# ` title plus 10+ of its long lines verbatim, fenced code ignored. Install never updates that copy. Names each file and title line; delete the copy. |
|
|
228
|
-
| `gh-mcp-token-unset-shell` / `gh-mcp-token-empty-shell` | `BKIT_GH_TOKEN` (GitHub MCP auth) unset/empty in shell while a `github` MCP server is configured — the whole tracker/PR/board MCP surface fails to connect. Suppressed in CI. |
|
|
254
|
+
| `gh-mcp-token-unset-shell` / `gh-mcp-token-empty-shell` | `BKIT_GH_TOKEN` (GitHub MCP auth) unset / empty in shell while a `github` MCP server is configured — the whole tracker/PR/board MCP surface fails to connect. Suppressed in CI. |
|
|
229
255
|
| `tracker-setup-none` / `-github` / `-linear` / `-jira` | Optional post-install decision — which issue tracker is wired (`bkit.tracker.default`). `none` nudges `bkit install --tracker=…`. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
230
256
|
| `github-project-board-sync-unconfigured` | GitHub tracker active but Projects v2 board sync is half-configured (`bkit.tracker.github.project` empty, absent or not a board URL, and/or `.mcp.json` lacks the `projects` toolset) — sync silently no-ops. Silence with `bkit.tracker.github.project: false`. |
|
|
231
257
|
| `github-project-token-scope` | A board is configured but `BKIT_GH_TOKEN` cannot reach it: a classic token lacks the `project` scope, or a fine-grained token's board query returns nothing. Board moves fall back to the MCP. Checked live via `gh`; skipped on cloud / CI. |
|
|
232
258
|
| `dep-updater-absent` | No Renovate or Dependabot config. Copy one example and own it. `bkit.dependencies.updater: "none"` silences this. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
233
259
|
| `dep-updater-both` | Both updater configs are present. Keep one. |
|
|
260
|
+
| `dep-updater-unset` | Blocker. One updater's config is present but `bkit.dependencies.updater` does not name it (empty or unrecognised). Set it, or run `bkit upgrade`, which fills an empty value. |
|
|
261
|
+
| `dep-updater-mismatch` | Blocker. `bkit.dependencies.updater` names one updater (or `none`) while the other's config is present, or names an updater with no config. Fix the value or the config. |
|
|
234
262
|
| `cloud-router-none` / `cloud-router` | Optional post-install decision — post-CI auto-routing (`bkit.cloud.agent`). `none` (undecided) nudges `bkit install --auto=<variant>`, except under the jira tracker (local runs only); `cloud-router` is informational once `bkit-cloud.yml` is present. See [§ Optional post-install decisions](#optional-post-install-decisions). |
|
|
235
263
|
| `actions-write-permissions-missing` | `bkit-cloud.yml` present but repo Actions permissions are read-only / PR creation disabled — `actions/checkout` + `gh pr create` 403. Repo-level check; org policy can override. |
|
|
236
|
-
| `opencode-setup` |
|
|
264
|
+
| `opencode-setup` | OpenCode host installed (`--opencode=<provider>`) — names the provider key to set (e.g. `BKIT_OPENROUTER_API_KEY`; `BKIT_OPENCODE_API_KEY` for `opencode-zen` / `opencode-go`), confirms the pre-seeded base URL, and notes all four providers ship curated per-agent pins (re-pin via `.bkit/prompts.md` § Model Overrides). Verify with `bkit doctor` + `bkit status`. |
|
|
265
|
+
| `vale-not-installed` | `bkit:lint:prose` runs `bkit ci prose` but vale is not on PATH, so the prose gate fails |
|
|
237
266
|
| `vale-package-not-synced` | vale on PATH but `.vale/styles/write-good/` absent |
|
|
238
267
|
| `gate-missing-called-scripts` | A `bkit:gate:*` script still at bkit's default chains a script `package.json` does not declare (e.g. `typecheck`, `format:check`, `test`). Add it (`.bkit/templates.md` lists the tool scripts and devDeps) or rewrite the gate. |
|
|
239
|
-
| `gate-commit-repeats-push` | `bkit:gate:format` (pre-commit) runs a script the push gate runs again (e.g. `lint:prose`), so it runs on every commit and again on the push. Drop it from `bkit:gate:format`. |
|
|
268
|
+
| `gate-commit-repeats-push` | `bkit:gate:format` (pre-commit) runs a script the push gate runs again (e.g. `bkit:lint:prose`), so it runs on every commit and again on the push. Drop it from `bkit:gate:format`. |
|
|
240
269
|
| `gate-noop` | A `bkit:gate:*` script is empty or cannot fail (`true`, `:`, `exit 0`, `echo …`), so every agent run and push passes it. Warn-only, at install, `bkit check` and `bkit upgrade`, on every branch. Point it at real checks, or delete it and run `bkit upgrade` to restore bkit's default. |
|
|
241
270
|
| `gate-tier-not-wired` | `package.json` declares a deeper test tier (`test:integration`, `test:e2e`, `test:live`) that no `bkit:gate:*` script runs; the advisory prints the gate line to add. |
|
|
242
271
|
| `test-file-script-missing` | `package.json` does not declare `bkit:test:file`, so `/bkit-build` reports test-first as not enforced. The advisory prints the script contract and a Vitest line. |
|
|
272
|
+
| `lint-file-script-missing` | `package.json` declares `bkit:test:file` but not `bkit:lint:file`, so `bkit tests red` records a group's reds before the linter sees the tests, and a lint fix after it changes a frozen test file, which the code step's `steps finish` refuses. The advisory prints the script contract and ESLint / Ruff lines. |
|
|
273
|
+
| `gate-changed-script-missing` | `package.json` does not declare `bkit:gate:changed`, so build and debug agents run a whole gate after every change instead of checking only the changed files. The advisory prints the script contract and a Vitest + ESLint line. Silence it with `bkit.advisories.ignore`. |
|
|
274
|
+
|
|
275
|
+
Every `gate-*` advisory ends with what a gate may run, which bkit cannot check: no test that needs a deployed boundary or remote service outside the two `…-e2e` gates (`.bkit/workflows.md` § Local gate scripts).
|
|
243
276
|
|
|
244
|
-
Phase 1 and Phase 3 findings merged and deduplicated by `id
|
|
277
|
+
Phase 1 and Phase 3 findings are merged and deduplicated by `id`. Phase 3 wins on conflict, because re-detection is more accurate after the writes. Zero findings → no banner.
|
|
245
278
|
|
|
246
|
-
**`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only)
|
|
279
|
+
**`bkit check` (dry-run)** runs Phase 1 and Phase 3 (read-only): the same advisory set as `bkit install`, minus the writes. It changes no managed file (it regenerates the `.bkit/advisories.md` artifact), and it exits 1 when any managed-file write would occur in an installed module:
|
|
247
280
|
|
|
248
|
-
|
|
281
|
+
- Tier-2 JSON deep-containment or markered-block drift.
|
|
282
|
+
- A whole-file byte-equal mismatch.
|
|
283
|
+
- Host agent / command mirror content drift (would-write / orphan delete).
|
|
284
|
+
- Any file bkit writes (rendered agents / commands / skills, managed blocks, owned whole files) carrying a stale managed-version marker (`bkit-managed-stale`).
|
|
285
|
+
- A missing `bkit:gate:*` name, which counts as a write.
|
|
249
286
|
|
|
250
|
-
|
|
287
|
+
The gate covers the installed module set ({core, claude, cursor, codex, antigravity} plus OpenCode). Each module is detected by sentinel files: for a host, its `agents/` dir, and for antigravity, any of `.agents/plugins/bkit/{plugin.json,hooks.json,agents,skills,hooks}`, so a deleted plugin manifest is reported as a missing file, not an absent host. `bkit status` uses the same detection.
|
|
288
|
+
|
|
289
|
+
- **antigravity gated:** `.agents/plugins/bkit/**` (plugin manifest, hooks, agents, skills) and the root `GEMINI.md`.
|
|
290
|
+
- **OpenCode gated:** Drift in `.opencode/opencode.json` (the provider block + the recorded tracker's `mcp` entry + the permission sandbox) and in the `bkit-gateguard.js` / `bkit-readguard.js` / `bkit-rules.js` plugins fails `check`.
|
|
291
|
+
- Another tracker's `mcp` entry that the consumer edited, kept by a tracker switch, is not drift. `mcp-extra-server-linear--opencode-opencode-json` advises removing it.
|
|
292
|
+
- Render inputs fall back to the installed provider (`package.json` `bkit.providers.opencode.default`, authoritative for `opencode-zen` / `opencode-go`; all installed providers are tracked in `bkit.providers.opencode.installed: string[]`) and the recorded tracker, so a clean install across providers checks green, with no false drift.
|
|
293
|
+
- The remaining opt-in module (cloud) is not drift-gated.
|
|
294
|
+
|
|
295
|
+
A missing bkit-owned hook file also fails `check`, with one line per file naming it and the `bkit install` flag that restores it. This covers the hook files of every installed host (`.claude/hooks/*`, `.cursor/hooks/*`, `.codex/hooks/*`, `.agents/plugins/bkit/hooks/*`, `.opencode/plugin/bkit-gateguard.js`, `.opencode/plugin/bkit-readguard.js`, `.opencode/plugin/bkit-rules.js`). The hook commands skip a missing file (`test -f … || true`), so without this check the guard would be off with no signal.
|
|
296
|
+
|
|
297
|
+
Updater configs are not bkit files, so `bkit check` does not report them. Phase 3 stays read-only through read-only detector paths, not by being skipped.
|
|
298
|
+
|
|
299
|
+
**`bkit upgrade`** (not `--dry-run`) ends with the same read-only pass as `bkit check`: it prints the checklist and rewrites `.bkit/advisories.md` (`Mode: upgrade`). It only reports the drift and blockers it finds, and upgrade's exit code is unchanged.
|
|
300
|
+
|
|
301
|
+
**`PreflightFinding` shape** — a stable contract for downstream tooling:
|
|
251
302
|
|
|
252
303
|
```typescript
|
|
253
304
|
interface PreflightFinding {
|
|
@@ -258,9 +309,9 @@ interface PreflightFinding {
|
|
|
258
309
|
}
|
|
259
310
|
```
|
|
260
311
|
|
|
261
|
-
Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` lines. The console banner and the `.bkit/advisories.md` artifact render the same text
|
|
312
|
+
Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` lines. The console banner and the `.bkit/advisories.md` artifact render the same text, so copy either into a coding assistant to apply the fixes in sequence. After the findings, both list every firing setup tip (§ Setup tips).
|
|
262
313
|
|
|
263
|
-
**Dismissing an advisory (per package).** A detector can be right in general and still fire where the condition is deliberately not applicable
|
|
314
|
+
**Dismissing an advisory (per package).** A detector can be right in general and still fire where the condition is deliberately not applicable, such as a rule-linter whose test titles mention `@live`, or an integration lane mocked by design. Opt the owning package out in its `package.json`:
|
|
264
315
|
|
|
265
316
|
```json
|
|
266
317
|
{
|
|
@@ -273,20 +324,20 @@ Findings render as `--- i/N [severity] id ---` with `Detect:` and `Action:` line
|
|
|
273
324
|
<!-- prettier-ignore -->
|
|
274
325
|
| Rule | Behaviour |
|
|
275
326
|
| --- | --- |
|
|
276
|
-
| Scope | Per package, read from the
|
|
327
|
+
| Scope | Per package, read from the owning package's `package.json` — the package holding the test file for `tagged-tests-no-ci-home`, the repo root for `test-integration-env-not-asserted` (the only manifest it reads). A sibling package with a real finding stays flagged. |
|
|
277
328
|
| Severity | Advisory only. A `blocker` is never suppressible, whatever the manifest says. |
|
|
278
329
|
| Visibility | The console banner and `.bkit/advisories.md` carry one suppressed-advisory line per dismissal (`N advisory` / `N advisories`), so a stale opt-out cannot hide a finding silently. |
|
|
279
330
|
| Coverage | Per package: `tagged-tests-no-ci-home` and `test-integration-env-not-asserted`. Repo root: every setup tip id and every advisory a tip reuses (§ Setup tips). No other advisory is suppressible; an id matching no advisory or tip is ignored. |
|
|
280
331
|
|
|
281
332
|
## Optional post-install decisions
|
|
282
333
|
|
|
283
|
-
Two capabilities
|
|
334
|
+
Two capabilities are opt-in, and a plain host / tooling install never wires them. The default install never enables them, and the post-install advisory banner nudges you to choose, once. Each choice is recorded in `package.json` (`bkit.tracker.default`, `bkit.cloud.agent`), so the nudge knows whether you've decided or deliberately opted out.
|
|
284
335
|
|
|
285
336
|
<!-- prettier-ignore -->
|
|
286
337
|
| Decision | Default | Opt-in command | Advisory when unset |
|
|
287
338
|
| --- | --- | --- | --- |
|
|
288
339
|
| **Issue tracker** | `none` (workflows run; tracker calls are no-ops) | `bkit install --tracker=github` (`BKIT_GH_TOKEN`) `--tracker=linear` (`BKIT_LINEAR_API_KEY`) or `--tracker=jira` (`BKIT_JIRA_API_KEY` + `bkit.tracker.jira.site` / `bkit.tracker.jira.project`) | `tracker-setup-none` |
|
|
289
|
-
| **Cloud agents** | none (zero cloud footprint) | `bkit install --auto=claude\|cursor\|opencode` — records the choice and points at the copy-and-own templates: `.claude/hooks/bkit-cloud-bootstrap.sh` (claude), the `bkit-cloud.yml` (claude +
|
|
340
|
+
| **Cloud agents** | none (zero cloud footprint) | `bkit install --auto=claude\|cursor\|opencode` — records the choice and points at the copy-and-own templates: `.claude/hooks/bkit-cloud-bootstrap.sh` (claude), the `bkit-cloud.yml` (claude + OpenCode jobs, secret-gated) and the Cursor Dockerfile/environment.json | `cloud-router-none` |
|
|
290
341
|
|
|
291
342
|
**Dependency updater.** Copy one example and own it.
|
|
292
343
|
|
|
@@ -297,28 +348,38 @@ Two capabilities **opt-in** — never wired by plain host/tooling install. Defau
|
|
|
297
348
|
| Renovate self-hosted runner | `.bkit/templates/.github/workflows/bkit-renovate.yml` |
|
|
298
349
|
| Dependabot | `.bkit/templates/.github/dependabot.yml` |
|
|
299
350
|
|
|
300
|
-
Use one
|
|
351
|
+
Use one, and record it in `bkit.dependencies.updater` (`"renovate"` / `"dependabot"`). Install and upgrade fill an empty value from the config present. `"none"` skips the install-time absence advisory. `bkit check` emits `dep-updater-absent` and `dep-updater-both`, and blocks on `dep-updater-unset` / `dep-updater-mismatch` when the value and the configs disagree. Setup: `docs/deployments.md` § Dependency updaters.
|
|
301
352
|
|
|
302
|
-
**Security scan.**
|
|
353
|
+
**Security scan.** An updater only offers fixes once a fixed release exists. To fail CI on known-vulnerable packages, risky config or committed secrets, copy `.bkit/templates/.github/workflows/bkit-trivy.yml` and own it. It also runs daily, and you accept findings in `.trivyignore.yaml`. There is no advisory, and `bkit tips` suggests it. Setup: `.bkit/templates.md` § Trivy.
|
|
303
354
|
|
|
304
|
-
**Test lint.** JS / TS repos, to fail `lint` on a test that cannot fail (no assertion, branch inside a test, unawaited promise):
|
|
355
|
+
**Test lint.** In JS / TS repos, to fail `lint` on a test that cannot fail (no assertion, a branch inside a test, an unawaited promise):
|
|
305
356
|
|
|
306
|
-
|
|
357
|
+
1. Copy and own `.bkit/templates/.oxlintrc.json`.
|
|
358
|
+
2. Add `oxlint` + `oxlint-tsgolint`.
|
|
359
|
+
3. Set `lint` to `oxlint -c .oxlintrc.json --type-aware --deny-warnings`.
|
|
360
|
+
|
|
361
|
+
There is no advisory, and `bkit tips` suggests it. Setup: `.bkit/templates.md` § Oxlint.
|
|
362
|
+
|
|
363
|
+
**All templates.** You copy and own them, and they are never installed. Catalog and install steps: `.bkit/templates.md`.
|
|
307
364
|
|
|
308
365
|
**Why opt-in, not part of a default install:**
|
|
309
366
|
|
|
310
|
-
- **Tracker** wires real credentials and MCP servers into workflows
|
|
311
|
-
- **Cloud agents** run through the phase-routed `bkit-cloud.yml` template
|
|
367
|
+
- **Tracker** wires real credentials and MCP servers into workflows, so the consumer must choose the provider. bkit can't guess.
|
|
368
|
+
- **Cloud agents** run through the phase-routed `bkit-cloud.yml` template plus the cloud env scaffolding (`.claude/hooks/bkit-cloud-bootstrap.sh`, and the `.cursor/Dockerfile` + `.cursor/environment.json` templates). The template auto-dispatches bkit-ship on CI pass and bkit-debug on CI fail, and runs design / plan / build only through `workflow_dispatch`.
|
|
369
|
+
- The workflow carries a claude job and an OpenCode job, each runtime-gated on its provider secret, so each is inert without its key. claude needs the `ANTHROPIC_API_KEY` repo secret or the federation repo variables (+ the Claude GitHub App). OpenCode needs `OPENCODE_PROVIDER_KEY`.
|
|
370
|
+
- Both need GitHub Actions write permissions, the GitHub tracker, and (for the Cursor half) a dashboard trigger, and the tracker itself is opt-in.
|
|
371
|
+
- The env scaffolding is inert until the Claude / Cursor cloud env is wired in the dashboard.
|
|
372
|
+
- Autonomous routing by default, wired to an unconfigured tracker, is the wrong default, so an install without `--auto` ships zero cloud footprint.
|
|
312
373
|
|
|
313
374
|
**How to decide:**
|
|
314
375
|
|
|
315
|
-
1. Run `bkit install --claude --cursor` (or whichever modules you want).
|
|
316
|
-
2. Pick tracker: `bkit install --tracker=github` (or `linear` / `jira`).
|
|
317
|
-
3. Copy one updater example (table above). Land Renovate config on the default branch before installing the App.
|
|
318
|
-
4. Enable cloud agents: `bkit install --auto=claude|cursor|opencode`.
|
|
319
|
-
5. **To opt out and silence the nudge**, set the field to `"none"` in `package.json` (`bkit.tracker.default` / `bkit.dependencies.updater` / `bkit.cloud.agent`).
|
|
376
|
+
1. Run `bkit install --claude --cursor` (or whichever modules you want). If you have not decided yet, the post-install banner lists `tracker-setup-none`, `dep-updater-absent` and `cloud-router-none`.
|
|
377
|
+
2. Pick a tracker: `bkit install --tracker=github` (or `linear` / `jira`). It needs no host flag, and it re-renders every installed host. The choice is persisted to `bkit.tracker.default`, and future installs preserve it (switching is free).
|
|
378
|
+
3. Copy one updater example (table above). Land the Renovate config on the default branch before installing the App. The next `bkit install` / `bkit upgrade` sets `bkit.dependencies.updater` to it.
|
|
379
|
+
4. Enable cloud agents: `bkit install --auto=claude|cursor|opencode`. The choice is persisted to `bkit.cloud.agent`, and install prints the secrets + permissions + dashboard checklist (`bkit-auto-setup`). The shipped `bkit-cloud.yml` carries a claude job (`ANTHROPIC_API_KEY` repo secret or federation repo variables, see `.bkit/cloud.md` § Claude — workload identity federation) and an OpenCode job (`OPENCODE_PROVIDER_KEY`), each runtime-gated.
|
|
380
|
+
5. **To opt out and silence the nudge**, set the field to `"none"` in `package.json` (`bkit.tracker.default` / `bkit.dependencies.updater` / `bkit.cloud.agent`). The advisory then stays quiet. The `""` that install seeds means undecided, and keeps the nudge.
|
|
320
381
|
|
|
321
|
-
|
|
382
|
+
To reverse the tracker or cloud-agent choice, re-run install with the other flag. Updater files stay until you delete them.
|
|
322
383
|
|
|
323
384
|
**GitHub notifications.** bkit's agents comment as you, so every workflow those comments trigger notifies you, even ones that skip. To see only failures: GitHub → Settings → Notifications → System → Actions → "Only notify for failed workflows".
|
|
324
385
|
|
|
@@ -336,7 +397,7 @@ bkit tips --all # every firing tip
|
|
|
336
397
|
<!-- prettier-ignore -->
|
|
337
398
|
| Rule | Behaviour |
|
|
338
399
|
| --- | --- |
|
|
339
|
-
| Order | One fixed priority list. `--workflow=<name>` moves the tips that matter in that workflow to the front: tracker, GitHub token, `.bkit/.env` and direnv matter in every workflow, so they lead until fixed; then e.g. context-fetch for debug, Husky / slop-scan / Oxlint for build, CI workflow / cloud for ship, Serena / CI workflow / graphify / updater / Trivy for `audit`, Serena for `utility`. |
|
|
400
|
+
| Order | One fixed priority list. The upgrade tip (a newer bkit is out, per the answer `bkit repo info` caches) comes first everywhere, since an outdated bkit runs old workflow text, and no `bkit.advisories.ignore` entry silences it. `--workflow=<name>` moves the tips that matter in that workflow to the front: tracker, GitHub token, `.bkit/.env` and direnv matter in every workflow, so they lead until fixed; then e.g. context-fetch for debug, Husky / slop-scan / Oxlint for build, CI workflow / cloud for ship, Serena / CI workflow / graphify / updater / Trivy for `audit`, Serena for `utility`. |
|
|
340
401
|
| Detection | Local only — files, settings, environment; no network. A tip clears once its local half exists; dashboard steps live in the tip text. |
|
|
341
402
|
| Reuse | A tip for a gap an advisory already detects calls that advisory's detector — tip and advisory never disagree. |
|
|
342
403
|
| Artifact | `bkit install` / `check` / `upgrade` / `doctor` list every firing tip, with its id, in `.bkit/advisories.md` § Setup tips and the console banner: line, why, caution, ask-your-agent sentence, agent steps. |
|
|
@@ -346,7 +407,7 @@ bkit tips --all # every firing tip
|
|
|
346
407
|
|
|
347
408
|
## Doctor
|
|
348
409
|
|
|
349
|
-
`bkit doctor` is **diagnostic verb
|
|
410
|
+
`bkit doctor` is the **diagnostic verb**: it runs the Phase 1 preflight + Phase 3 credential detectors, and exits 0. It changes no managed file. Like `bkit check`, it regenerates the `.bkit/advisories.md` artifact, and it creates `.bkit/` if absent, so a repo that never installed bkit gains that one file.
|
|
350
411
|
|
|
351
412
|
```bash
|
|
352
413
|
# Diagnose drift without running install
|
|
@@ -355,16 +416,17 @@ bkit doctor
|
|
|
355
416
|
|
|
356
417
|
Use `bkit doctor` to:
|
|
357
418
|
|
|
358
|
-
- Check `BKIT_GH_TOKEN`
|
|
359
|
-
- Surface `bkit-version-pin-stale` advisory (installed version ahead of `.bkit/version`).
|
|
360
|
-
- Preview all advisories `bkit install` would show
|
|
361
|
-
- Verify environment ready before `bkit install` on new machine.
|
|
419
|
+
- Check that `BKIT_GH_TOKEN` is present in the shell (GitHub MCP auth), and check the cloud-router claude credential (`ANTHROPIC_API_KEY` repo secret or federation repo variables). It also flags a key shadowing federation, and an adopted `bkit-cloud.yml` too old for federation.
|
|
420
|
+
- Surface the `bkit-version-pin-stale` advisory (installed version ahead of `.bkit/version`).
|
|
421
|
+
- Preview all the advisories `bkit install` would show after install, without triggering writes.
|
|
422
|
+
- Verify the environment is ready before `bkit install` on a new machine.
|
|
362
423
|
- Detect macOS GUI-isolation (`bkit cursor` / `bkit opencode`): see `.bkit/providers.md` § macOS GUI-isolation.
|
|
363
|
-
|
|
424
|
+
|
|
425
|
+
`bkit doctor` always exits 0. When it finds advisories, it prints them in the same checklist banner format as `bkit install`. When it finds none, it prints `[bkit-doctor] No advisories found.`
|
|
364
426
|
|
|
365
427
|
## Uninstall
|
|
366
428
|
|
|
367
|
-
`bkit uninstall` surgically removes bkit-managed content while preserving consumer customisations. The `.bkit/core` / `.bkit/shared` payload view links go with a full/core uninstall
|
|
429
|
+
`bkit uninstall` surgically removes bkit-managed content while preserving consumer customisations. The `.bkit/core` / `.bkit/shared` payload view links go with a full / core uninstall. It removes symlinks only, because a real directory at either path is consumer content and stays.
|
|
368
430
|
|
|
369
431
|
```bash
|
|
370
432
|
# Uninstall EVERYTHING — all modules, including the cloud add-on if present.
|
|
@@ -396,43 +458,51 @@ bkit uninstall --nuke --yes
|
|
|
396
458
|
| Format | Behaviour |
|
|
397
459
|
| --- | --- |
|
|
398
460
|
| `fully-managed` | Always deleted (bkit owns 100% of the file). |
|
|
399
|
-
| `markered-text` | bkit block stripped; consumer content above/below preserved. File deleted if only whitespace remains — or, for a bkit-seeded markdown file (`AGENTS.md`/`CLAUDE.md`), if only its `# Title` heading husk remains. |
|
|
461
|
+
| `markered-text` | bkit block stripped; consumer content above / below preserved. File deleted if only whitespace remains — or, for a bkit-seeded markdown file (`AGENTS.md`/`CLAUDE.md`), if only its `# Title` heading husk remains. |
|
|
400
462
|
| `byte-equal-text` | Deleted only if current hash matches the hash `.bkit/version` recorded when bkit last wrote it (`canonicalHashes`). Consumer modifications → preserved. `canonicalHashes` is internal state `bkit check` does not verify: a hand-edited or corrupted entry makes uninstall keep that file as consumer-modified (`--force` deletes it anyway) and upgrade's whole-file diff report a conflict instead of updating it. Rendered `.bkit/*.md` skip that diff: upgrade always re-renders them, and `bkit check` flags a hand edit. |
|
|
401
463
|
| `json` | bkit's keys stripped; consumer keys preserved. `.mcp.json` / `.cursor/mcp.json`: only bkit's tracker entry is removed, and only while it still equals the template. `.opencode/opencode.json`: every `mcp` tracker entry (`github`, `linear`, `jira`) and every `provider` block of a supported provider is removed while it still equals what install renders — all the earlier installs left, not just the active one; an edited entry is kept whole. File deleted when nothing is left. |
|
|
402
464
|
|
|
403
465
|
### Idempotency
|
|
404
466
|
|
|
405
|
-
Running `bkit uninstall` twice is safe
|
|
467
|
+
Running `bkit uninstall` twice is safe, because later runs skip absent files and produce zero writes.
|
|
406
468
|
|
|
407
469
|
### What a full uninstall preserves
|
|
408
470
|
|
|
409
|
-
|
|
471
|
+
A bare uninstall removes bkit-managed files and strips bkit-managed blocks, but it is not a guaranteed zero-footprint wipe. In `docs/`, bkit's block (managed marker included) is stripped from every installed `docs/*.md`, a file holding nothing else is deleted, and the owned `docs/templates/bkit-*.md` are deleted. It deliberately leaves:
|
|
472
|
+
|
|
473
|
+
- everything outside `bkit:start` / `bkit:end` in `docs/*.md`, `.agents/context.md`, `.agents/skills.md` and the other managed-block files;
|
|
474
|
+
- your own files in `docs/` and `docs/templates/`;
|
|
475
|
+
- every file you copied from `.bkit/templates/`;
|
|
476
|
+
- any owned whole-file the consumer modified (hash mismatch → preserved);
|
|
477
|
+
- generated artefacts that are not manifest-tracked (`.bkit/advisories.md`, `.bkit/friction.jsonl`, the newest-release cache `.git/bkit-latest-version.json`).
|
|
478
|
+
|
|
479
|
+
Use `--nuke` to force-remove every manifest-listed bkit file regardless of consumer modifications. The generated artefacts are still yours to delete by hand.
|
|
410
480
|
|
|
411
481
|
## Phase 3 exit-1 and recovery
|
|
412
482
|
|
|
413
|
-
When `bkit install` detects
|
|
483
|
+
When `bkit install` detects a blocker-severity finding in Phase 3 (for example `owned-hook-missing`: a bkit-owned hook file is gone, so the guard or setup step it holds does not run), it exits 1 and prints a single-line recovery command:
|
|
414
484
|
|
|
415
485
|
```
|
|
416
486
|
[bkit-install] 1 Phase 3 blocker(s) detected. Recovery:
|
|
417
487
|
bkit uninstall <flags> && <fix the issue> && bkit install <flags>
|
|
418
488
|
```
|
|
419
489
|
|
|
420
|
-
Advisories (non-blockers) informational only
|
|
490
|
+
Advisories (non-blockers) are informational only, and do not trigger exit-1.
|
|
421
491
|
|
|
422
492
|
### --auto-revert
|
|
423
493
|
|
|
424
|
-
Add `--auto-revert` to `bkit install` to automatically run `bkit uninstall` in-process when Phase 3 blocker fires:
|
|
494
|
+
Add `--auto-revert` to `bkit install` to automatically run `bkit uninstall` in-process when a Phase 3 blocker fires:
|
|
425
495
|
|
|
426
496
|
```bash
|
|
427
497
|
bkit install --auto-revert
|
|
428
498
|
```
|
|
429
499
|
|
|
430
|
-
|
|
500
|
+
This is useful in CI scripts to guarantee a clean state on failure.
|
|
431
501
|
|
|
432
502
|
## Install staging directory
|
|
433
503
|
|
|
434
|
-
`bkit install` renders derived files (
|
|
504
|
+
`bkit install` renders derived files (for example `.opencode/opencode.json`) into the `.bkit-staging/` scratch directory before merging them into the consumer destinations. The scratch directory is cleaned up after every run, on success and failure alike, and never persists in committed consumer repo state.
|
|
435
505
|
|
|
436
|
-
**Not a cross-module transaction.** Modules write directly to destinations
|
|
506
|
+
**Not a cross-module transaction.** Modules write directly to their destinations, so `bkit install` is not atomic across modules. A failure partway (for example a hand-broken `.claude/settings.json` that makes the JSON merge throw) leaves the earlier modules' files written and `.bkit/version` unpinned. The error is surfaced, not swallowed.
|
|
437
507
|
|
|
438
|
-
**Recovery is re-run.** `bkit install` idempotent
|
|
508
|
+
**Recovery is re-run.** `bkit install` is idempotent: fix the offending file and re-run to complete. `bkit uninstall` removes whatever was written.
|