@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
|
@@ -1,51 +1,51 @@
|
|
|
1
|
-
<!-- Note: Plans live at `docs/plans/{YYYYMM}/{FID}-plan.md` (canonical month bucket). `{YYYYMM}` = creation month, set once by the first workflow run for `{FID}`. Logs sit at `docs/plans/{YYYYMM}/logs/{FID}/` and are delete-eligible. The canonical copy is stamped with a `bkit:anchor` block recording the base commit (`baseSha`), its ref (`baseRef`), and the design it targets (`designPath`, `designBaseSha`); never hand-author or edit it. `@bkit-plan-generate` fills this template. -->
|
|
2
|
-
|
|
3
1
|
<!-- bkit:start -->
|
|
4
2
|
|
|
5
3
|
{{BKIT_MANAGED_MARKER}}
|
|
6
4
|
|
|
5
|
+
<!-- Note: @bkit-plan-generate fills this template. The plan lives at `docs/plans/{YYYYMM}/{FID}-plan.md`, the canonical month bucket, where `{YYYYMM}` is the month the first workflow run for `{FID}` created it, set once. Logs sit at `docs/plans/{YYYYMM}/logs/{FID}/`, and may be deleted. The canonical copy is stamped with a `bkit:anchor` block that records the base commit (`baseSha`), its ref (`baseRef`) and the design it targets (`designPath`, `designBaseSha`). NEVER write or edit that block by hand. -->
|
|
6
|
+
|
|
7
7
|
# [Plan Title] Implementation Plan
|
|
8
8
|
|
|
9
9
|
> [!CAUTION]
|
|
10
|
-
> **Purpose:**
|
|
10
|
+
> **Purpose:** The implementation plan: pre-flight checks, gates, the runbook, verification and rollback.
|
|
11
11
|
|
|
12
12
|
## Context & Goals
|
|
13
13
|
|
|
14
|
-
[
|
|
14
|
+
[The problem or feature, and why it is needed. Initially set to `PENDING`.]
|
|
15
15
|
|
|
16
16
|
**Related Issues:**
|
|
17
17
|
|
|
18
|
-
- [`#N — title (state)` per related issue.
|
|
18
|
+
- [One `#N — title (state)` line per related issue. **If** none → `None`. Initially set to `PENDING`.]
|
|
19
19
|
|
|
20
20
|
---
|
|
21
21
|
|
|
22
22
|
## 👤 ⚠️ Acceptance Scenario
|
|
23
23
|
|
|
24
24
|
> [!CAUTION]
|
|
25
|
-
>
|
|
26
|
-
>
|
|
25
|
+
> 🛑 The owner reads and confirms this section.
|
|
26
|
+
> This is the feature's testable contract. The implementation, the tests and the verification all follow from what you confirm here, so a mistake here carries into every later step.
|
|
27
27
|
>
|
|
28
|
-
> **You only need 👤-marked sections** (Acceptance Scenario, Breaking Changes, Open Questions & Assumptions).
|
|
28
|
+
> **You only need 👤-marked sections** (Acceptance Scenario, Breaking Changes, Open Questions & Assumptions). The agent handles the rest.
|
|
29
29
|
|
|
30
30
|
### Narrative
|
|
31
31
|
|
|
32
|
-
[
|
|
32
|
+
[One or two sentences from the user's side: what they do, and what they get back. Initially set to `PENDING`.]
|
|
33
33
|
|
|
34
34
|
### Success Criteria
|
|
35
35
|
|
|
36
|
-
[Up to 5 measurable outcomes
|
|
36
|
+
[Up to 5 measurable outcomes. Initially set to `PENDING`.]
|
|
37
37
|
|
|
38
38
|
### Process Sketch
|
|
39
39
|
|
|
40
|
-
- **WHEN** [trigger
|
|
41
|
-
- **WHEN** [next step] **→ THEN** [outcome]
|
|
42
|
-
- **IF** [edge case
|
|
40
|
+
- **WHEN** [the trigger or user action] **→ THEN** [the observable outcome]
|
|
41
|
+
- **WHEN** [the next step] **→ THEN** [its outcome]
|
|
42
|
+
- **IF** [an edge case or failure, mirroring an Edge Cases row] **→ THEN** [how it is handled]
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
_e.g.,_ **WHEN** a user submits the form with a valid file **→ THEN** it is queued and a receipt is shown; **IF** the file is malformed **→ THEN** it is rejected inline and nothing is queued.
|
|
45
45
|
|
|
46
46
|
### Concrete Example
|
|
47
47
|
|
|
48
|
-
**Setup:** [
|
|
48
|
+
**Setup:** [The user's role, the existing state and the context]
|
|
49
49
|
|
|
50
50
|
**Steps:**
|
|
51
51
|
|
|
@@ -53,28 +53,28 @@ _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN**
|
|
|
53
53
|
2. User [does X] → System [responds with Y]
|
|
54
54
|
3. …
|
|
55
55
|
|
|
56
|
-
**Outcome:** [
|
|
56
|
+
**Outcome:** [The end state the user sees that proves success]
|
|
57
57
|
|
|
58
58
|
### Edge Cases
|
|
59
59
|
|
|
60
60
|
<!-- prettier-ignore -->
|
|
61
61
|
| Scenario | Expected Behavior |
|
|
62
62
|
| --- | --- |
|
|
63
|
-
| [
|
|
64
|
-
| [e.g., concurrent edit from another device] | [e.g., last
|
|
63
|
+
| [a design Key Edge Case, or a case the plan adds] | [the specific behavior] |
|
|
64
|
+
| [e.g., a concurrent edit from another device] | [e.g., the last write wins, with no crash] |
|
|
65
65
|
|
|
66
66
|
### Derived Test Matrix
|
|
67
67
|
|
|
68
|
-
`Type`
|
|
68
|
+
`Type` is a tier from `docs/testing.md`: Static, Unit, Integration, @live (golden), E2E, fresh-DB replay or Smoke. `Task` is the one runbook task that lands the row's test.
|
|
69
69
|
|
|
70
70
|
<!-- prettier-ignore -->
|
|
71
|
-
| Test description | Type | Target file |
|
|
72
|
-
| --- | --- | --- |
|
|
73
|
-
| [e.g.,
|
|
74
|
-
| [e.g.,
|
|
75
|
-
| [e.g., API endpoint enforces tenant isolation] | Integration | [e.g
|
|
76
|
-
| [e.g.,
|
|
77
|
-
| [e.g.,
|
|
71
|
+
| Test description | Type | Target file | Task |
|
|
72
|
+
| --- | --- | --- | --- |
|
|
73
|
+
| [e.g., happy path: a user creates an event and sees it in the list] | E2E | [e.g., `apps/web/e2e/[feature].spec.ts`] | 2 |
|
|
74
|
+
| [e.g., the service parses the payload correctly] | Unit | [e.g., `packages/[pkg]/[module].test.ts`] | 2 |
|
|
75
|
+
| [e.g., the API endpoint enforces tenant isolation] | Integration | [e.g., `packages/api/[feature].integration.test.ts`] | 2 |
|
|
76
|
+
| [e.g., the real third-party API returns the expected shape and a boundary-only identity, not just "did not throw"] | @live (golden) | [e.g., `packages/[pkg]/[feature].live.test.ts`] | 2 |
|
|
77
|
+
| [e.g., the new migration replays from empty and the seed loads] | fresh-DB replay | [e.g., `packages/db/migrations/*`] (replayed by `bkit-tests-migration`) | 1 |
|
|
78
78
|
|
|
79
79
|
### 👤 ✅ Human Confirmation
|
|
80
80
|
|
|
@@ -85,27 +85,26 @@ _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN**
|
|
|
85
85
|
## 👤 ⚠️ Breaking Changes & Naming Review
|
|
86
86
|
|
|
87
87
|
> [!CAUTION]
|
|
88
|
-
>
|
|
89
|
-
> Review proposed names and breaking changes below.
|
|
88
|
+
> 🛑 The owner reads and confirms this section.
|
|
90
89
|
|
|
91
|
-
[
|
|
90
|
+
[Each proposed name (page, file, database table, route, API contract) and each breaking change (database structure, global layout). **If** none → `None`. Initially set to `PENDING`.]
|
|
92
91
|
|
|
93
92
|
### 👤 ✅ Human Confirmation
|
|
94
93
|
|
|
95
|
-
- [ ] **Breaking Changes confirmed:** I have reviewed
|
|
94
|
+
- [ ] **Breaking Changes confirmed:** I have reviewed every breaking change and naming decision above.
|
|
96
95
|
|
|
97
96
|
---
|
|
98
97
|
|
|
99
98
|
## 👤 ⚠️ Open Questions & Assumptions
|
|
100
99
|
|
|
101
100
|
> [!CAUTION]
|
|
102
|
-
>
|
|
103
|
-
>
|
|
101
|
+
> 🛑 The owner reads and confirms this section.
|
|
102
|
+
> These are the unknowns and assumptions this plan relies on. An unresolved question is a risk, and a wrong assumption breaks what follows. **If** there are none → write `None`.
|
|
104
103
|
|
|
105
|
-
- **Assumption:** [what the plan takes as given] → [what breaks if it
|
|
106
|
-
- **Open Question:** [decision needed] → [who
|
|
107
|
-
- **Options:** A — [
|
|
108
|
-
- **Recommended:** [
|
|
104
|
+
- **Assumption:** [what the plan takes as given] → [what breaks if it is wrong]
|
|
105
|
+
- **Open Question:** [the decision needed] → [who resolves it, and how]
|
|
106
|
+
- **Options:** A) [option] — [trade-off] · B) [option] — [trade-off] · C) [option] — [trade-off, optional]
|
|
107
|
+
- **Recommended:** A) [option] — [why, in one line]
|
|
109
108
|
- **Default if unanswered:** [what the agent proceeds with]
|
|
110
109
|
|
|
111
110
|
### 👤 ✅ Human Confirmation
|
|
@@ -116,190 +115,192 @@ _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN**
|
|
|
116
115
|
|
|
117
116
|
## Alternative Approaches & Recommendations
|
|
118
117
|
|
|
119
|
-
[
|
|
118
|
+
[The paths rejected and why, and recommendations for a future phase. Initially set to `PENDING`.]
|
|
120
119
|
|
|
121
120
|
## Out of Scope
|
|
122
121
|
|
|
123
|
-
[
|
|
122
|
+
[Each excluded item, marked `Exempt`. **If** none → `None`. Initially set to `PENDING`.]
|
|
124
123
|
|
|
125
124
|
<!-- prettier-ignore -->
|
|
126
125
|
| Excluded item | Why `Exempt` | Where it belongs |
|
|
127
126
|
| --- | --- | --- |
|
|
128
|
-
| [feature
|
|
127
|
+
| [the excluded feature or fix] | [why it only adds to the plan's goal] | [a design non-goal, a follow-up issue or a future phase] |
|
|
128
|
+
| [e.g., bulk status change] | [e.g., single changes meet the goal, and bulk changes add to it] | [e.g., follow-up #N] |
|
|
129
129
|
|
|
130
130
|
## Suggested Scope Expansion
|
|
131
131
|
|
|
132
|
-
[
|
|
132
|
+
[The candidates that overlap this plan's surfaces. **If** none → `None`. Initially set to `PENDING`.]
|
|
133
133
|
|
|
134
134
|
<!-- prettier-ignore -->
|
|
135
135
|
| Candidate | Source | Overlaps | Recommendation |
|
|
136
136
|
| --- | --- | --- | --- |
|
|
137
|
-
| [what it is] | [`#N
|
|
137
|
+
| [what it is] | [`#N`, `docs/deferrals.jsonl`, `docs/failures.jsonl` or an audit finding id] | [the surface or task it touches] | [fold in, keep deferred, or needs a design decision] |
|
|
138
138
|
|
|
139
139
|
## Security & Privacy
|
|
140
140
|
|
|
141
|
-
- [ ] **New API Route** — auth guard (e.g
|
|
142
|
-
- [ ] **New DB Table/Column** — deny-by-default row
|
|
143
|
-
- [ ] **Role-Gated Mutation** — role checked at the API layer.
|
|
144
|
-
- [ ] **User Input** —
|
|
145
|
-
- [ ] **PII** —
|
|
146
|
-
- [ ] **Redirect URL** — allow-list
|
|
147
|
-
- [ ] **Webhook** — signature verified
|
|
148
|
-
- [ ] **New Secret/Env Var** — in the env schema and the project's secret manager.
|
|
141
|
+
- [ ] **New API Route** — an auth guard (e.g., a `requireMember`-style check). **If** the route is auth-adjacent → a rate limit as well.
|
|
142
|
+
- [ ] **New DB Table/Column** — a deny-by-default row or tenant access policy (e.g., a row-level policy in the database), scoped to the tenant.
|
|
143
|
+
- [ ] **Role-Gated Mutation** — the role is checked at the API layer.
|
|
144
|
+
- [ ] **User Input** — validated against a schema in the handler (e.g., the schema library's parse call).
|
|
145
|
+
- [ ] **PII** — kept out of logs, and the audit or CDC trigger is updated for new monitored columns.
|
|
146
|
+
- [ ] **Redirect URL** — validated against an allow-list.
|
|
147
|
+
- [ ] **Webhook** — the signature is verified, and the secret is in the env schema.
|
|
148
|
+
- [ ] **New Secret/Env Var** — in the env schema and in the project's secret manager.
|
|
149
149
|
|
|
150
|
-
|
|
150
|
+
[**If** no row applies → write "None — no new routes, DB writes, secrets, or user input."]
|
|
151
151
|
|
|
152
152
|
## Pre-Flight / Dependencies
|
|
153
153
|
|
|
154
154
|
### Core
|
|
155
155
|
|
|
156
|
-
- [ ] **Package Management:** packages declared
|
|
157
|
-
- [ ] **Dependency Versions:** outdated
|
|
158
|
-
- [ ] **Existing-Solution Search (reuse over duplicate):** in-repo, dependency and ecosystem
|
|
159
|
-
- [ ] **User Context:**
|
|
160
|
-
- [ ] **Project Context:** relevant `docs/knowledge.jsonl` and `docs/decisions.jsonl` rows read.
|
|
161
|
-
- [ ] **Testing & Quality:** testing strategy matches `docs/testing.md`.
|
|
162
|
-
- [ ] **Prerequisite Plans:** [plans to finish first
|
|
156
|
+
- [ ] **Package Management:** the packages are declared, and the manifest and lockfile are in sync.
|
|
157
|
+
- [ ] **Dependency Versions:** outdated dependencies and the toolchain and stack CLI versions are checked.
|
|
158
|
+
- [ ] **Existing-Solution Search (reuse over duplicate):** the in-repo, dependency and ecosystem searches are recorded in `Reuse Inventory`.
|
|
159
|
+
- [ ] **User Context:** access to the files is confirmed, and missing user information is requested.
|
|
160
|
+
- [ ] **Project Context:** the relevant `docs/knowledge.jsonl` and `docs/decisions.jsonl` rows are read.
|
|
161
|
+
- [ ] **Testing & Quality:** the testing strategy matches `docs/testing.md`.
|
|
162
|
+
- [ ] **Prerequisite Plans:** [the plans to finish first. **If** none → `None`.]
|
|
163
163
|
|
|
164
164
|
### Conditional
|
|
165
165
|
|
|
166
|
-
- [ ] **Secrets & Env Vars:** secret store and service-account roles checked.
|
|
167
|
-
- [ ] **Schema State:** database state confirmed against `docs/data-schema.md`.
|
|
168
|
-
- [ ] **Architecture & UI:** `docs/architecture.md
|
|
169
|
-
- [ ] **Observability:** logs, audit tables and traces
|
|
170
|
-
- [ ] **Notifications:** alert
|
|
166
|
+
- [ ] **Secrets & Env Vars:** the secret store and the service-account roles are checked.
|
|
167
|
+
- [ ] **Schema State:** the database state is confirmed against `docs/data-schema.md`.
|
|
168
|
+
- [ ] **Architecture & UI:** the topology is checked against `docs/architecture.md`, and any UI against `docs/design.md`.
|
|
169
|
+
- [ ] **Observability:** logs, audit tables and traces follow `docs/observability.md`.
|
|
170
|
+
- [ ] **Notifications:** the alert or toast tier follows the notifications doc.
|
|
171
171
|
|
|
172
172
|
### 🔒 Gate 1: Prerequisites Check
|
|
173
173
|
|
|
174
|
-
- [ ] **Acceptance Scenario confirmed:**
|
|
175
|
-
- [ ] **Breaking Changes confirmed:**
|
|
176
|
-
- [ ] **Open Questions confirmed:**
|
|
177
|
-
- [ ] **Security & Privacy checked:** applicable
|
|
178
|
-
- [ ] **Reuse Inventory complete:** every capability has a row with `Search performed` and `Decision
|
|
179
|
-
- [ ] **
|
|
174
|
+
- [ ] **Acceptance Scenario confirmed:** the `👤 ⚠️ Acceptance Scenario` checkbox is `[x]`, ticked by a human.
|
|
175
|
+
- [ ] **Breaking Changes confirmed:** the `👤 ⚠️ Breaking Changes & Naming Review` checkbox is `[x]`, ticked by a human.
|
|
176
|
+
- [ ] **Open Questions confirmed:** the `👤 ⚠️ Open Questions & Assumptions` checkbox is `[x]`, ticked by a human.
|
|
177
|
+
- [ ] **Security & Privacy checked:** every applicable row is verified, or `None` is justified.
|
|
178
|
+
- [ ] **Reuse Inventory complete:** every capability has a row with `Search performed` and `Decision` filled in.
|
|
179
|
+
- [ ] **Reuse reasons:** every `NEW` row cites its reason.
|
|
180
|
+
- [ ] **Gate 1 — Verified:** every item above, every Core item and every applicable Conditional item is checked.
|
|
180
181
|
|
|
181
182
|
## Data Schema Integration
|
|
182
183
|
|
|
183
|
-
[How this feature uses the existing schema and what changes
|
|
184
|
+
[How this feature uses the existing schema, and what changes. Initially set to `PENDING`.]
|
|
184
185
|
|
|
185
186
|
### Data Schema Usage
|
|
186
187
|
|
|
187
|
-
[
|
|
188
|
+
[The existing `docs/data-schema.md` tables and fields the feature reads (Input) or writes (Output). **If** none → `None`. Initially set to `PENDING`.]
|
|
188
189
|
|
|
189
|
-
- **Input (Read):** `users.id`, `items.title`
|
|
190
|
-
- **Output (Write):** `items.status`, `job_audits.log`]
|
|
190
|
+
- [e.g., **Input (Read):** `users.id`, `items.title`]
|
|
191
|
+
- [e.g., **Output (Write):** `items.status`, `job_audits.log`]
|
|
191
192
|
|
|
192
193
|
### Data Schema Changes
|
|
193
194
|
|
|
194
|
-
[
|
|
195
|
+
[The new tables, new fields and changed fields to record in `docs/data-schema.md`. **If** none → `None`. Initially set to `PENDING`.]
|
|
195
196
|
|
|
196
|
-
- **ADD:** `items.new_field` (type: text)
|
|
197
|
-
- **MODIFY:** `users.role` (added enum value)]
|
|
197
|
+
- [e.g., **ADD:** `items.new_field` (type: text)]
|
|
198
|
+
- [e.g., **MODIFY:** `users.role` (added enum value)]
|
|
198
199
|
|
|
199
200
|
## Reuse Inventory
|
|
200
201
|
|
|
201
|
-
[One row per capability the plan introduces
|
|
202
|
+
[One row per capability the plan introduces. Initially set to `PENDING`.]
|
|
202
203
|
|
|
203
204
|
<!-- prettier-ignore -->
|
|
204
205
|
| Capability | File | Search performed | Existing candidates | Decision | Justification |
|
|
205
206
|
| --- | --- | --- | --- | --- | --- |
|
|
206
|
-
| [what the plan must do] | `path/to/existing` | `grep -rn "..."
|
|
207
|
-
| [e.g., item status column] | `
|
|
208
|
-
| [e.g., status change action] | `packages/api/src/items/setStatus.ts` | [exact commands
|
|
207
|
+
| [what the plan must do] | `path/to/existing` | `grep -rn "..."`, references to `{symbol}`, `docs/capabilities.md`, `{framework} {capability} built-in` | `path/to/existing` — covers [X], missing [Y] | EXTEND | [what changes in it to close the gap] |
|
|
208
|
+
| [e.g., item status column] | `packages/db/migrations/{timestamp}_add_items_status.sql` | [the exact commands and queries run] | None — [what was searched] | NEW | [reason (a), (b) or (c)] |
|
|
209
|
+
| [e.g., status change action] | `packages/api/src/items/setStatus.ts` | [the exact commands and queries run] | None — [what was searched] | NEW | [reason (a), (b) or (c)] |
|
|
209
210
|
|
|
210
211
|
## Architecture & Component Changes
|
|
211
212
|
|
|
212
|
-
[
|
|
213
|
-
**Ledger rows:** [
|
|
213
|
+
[The files, grouped by area (DB, API, Backend, Frontend, Cron, Observability), with one heading per area. Initially set to `PENDING`.]
|
|
214
|
+
**Ledger rows:** [The backticked `key` of every `docs/decisions.jsonl` and `docs/deferrals.jsonl` row written for this plan, comma-separated. **If** none → write "None". Initially set to `PENDING`.]
|
|
214
215
|
|
|
215
216
|
### Database Migrations
|
|
216
217
|
|
|
217
|
-
[
|
|
218
|
+
[The new tables, columns and access policies (e.g., row-level policies), and the migration that adds them. Initially set to `PENDING`.]
|
|
218
219
|
|
|
219
220
|
### [Component Area 1]
|
|
220
221
|
|
|
221
|
-
[
|
|
222
|
+
[A summary of the component changes. Initially set to `PENDING`.]
|
|
222
223
|
|
|
223
224
|
#### [MODIFY] `path/to/file.ext`
|
|
224
225
|
|
|
225
|
-
- **Existence Check:** [file exists]
|
|
226
|
-
- [
|
|
226
|
+
- **Existence Check:** [the file exists]
|
|
227
|
+
- [The logic, schema or API contract changes.]
|
|
227
228
|
|
|
228
229
|
#### [new] `path/to/file.ext`
|
|
229
230
|
|
|
230
|
-
- **Reuse Check:** [`Reuse Inventory` row
|
|
231
|
-
- [
|
|
231
|
+
- **Reuse Check:** [the `Reuse Inventory` row, and reason (a), (b) or (c)]
|
|
232
|
+
- [The purpose, access policies, input validation and naming.]
|
|
232
233
|
|
|
233
234
|
#### [DELETE] `path/to/file.ext`
|
|
234
235
|
|
|
235
|
-
- [
|
|
236
|
+
- [The reason]
|
|
236
237
|
|
|
237
238
|
### Cron Jobs & Scheduled Tasks
|
|
238
239
|
|
|
239
|
-
[
|
|
240
|
+
[The scheduled tasks (e.g., a hosting platform's cron, a database scheduler or a background-job runner). **If** none → `None`. Initially set to `PENDING`.]
|
|
240
241
|
|
|
241
242
|
## Supersession Inventory
|
|
242
243
|
|
|
243
|
-
[
|
|
244
|
+
[The existing artifacts the new code replaces. **If** none → `None`. Initially set to `PENDING`.]
|
|
244
245
|
|
|
245
246
|
<!-- prettier-ignore -->
|
|
246
247
|
| Existing artifact | Replaced by | Decision | Justification |
|
|
247
248
|
| --- | --- | --- | --- |
|
|
248
|
-
| `path/to/old-thing` | `path/to/new-thing` | DELETE | [reason] |
|
|
249
|
+
| `path/to/old-thing` | `path/to/new-thing` | DELETE | [the reason] |
|
|
249
250
|
|
|
250
251
|
## Documentation Updates
|
|
251
252
|
|
|
252
|
-
[One row per doc this change touches
|
|
253
|
+
[One row per doc this change touches. Find any doc not listed here through `.agents/docs.md`.]
|
|
253
254
|
|
|
254
255
|
<!-- prettier-ignore -->
|
|
255
256
|
| Doc | Change required |
|
|
256
257
|
| --- | --- |
|
|
257
|
-
| `docs/knowledge.jsonl` | [learnings
|
|
258
|
+
| `docs/knowledge.jsonl` | [learnings and gotchas] |
|
|
258
259
|
| `docs/decisions.jsonl` | [architecture decisions] |
|
|
259
|
-
| `docs/architecture.md` | [topology
|
|
260
|
-
| `docs/technology.md` | [frameworks, libraries
|
|
261
|
-
| `docs/data-schema.md` | [new tables
|
|
262
|
-
| `docs/design.md` | [palette, typography
|
|
263
|
-
| `docs/testing.md` | [new test files
|
|
264
|
-
| `docs/observability.md` | [new log names
|
|
260
|
+
| `docs/architecture.md` | [topology or component changes] |
|
|
261
|
+
| `docs/technology.md` | [frameworks, libraries and conventions] |
|
|
262
|
+
| `docs/data-schema.md` | [new tables or columns] |
|
|
263
|
+
| `docs/design.md` | [palette, typography and components] |
|
|
264
|
+
| `docs/testing.md` | [new test files or patterns] |
|
|
265
|
+
| `docs/observability.md` | [new log names or spans] |
|
|
265
266
|
|
|
266
267
|
## Rollback Strategy
|
|
267
268
|
|
|
268
269
|
<!-- prettier-ignore -->
|
|
269
270
|
| Axis | Action | Notes |
|
|
270
271
|
| --- | --- | --- |
|
|
271
|
-
| **DB** | [
|
|
272
|
-
| **Code** | [
|
|
273
|
-
| **Risk window** | [
|
|
272
|
+
| **DB** | [A corrective migration that undoes the change. It is safe when the change only adds.] | Merged migrations are immutable, so ship the corrective migration through CI's migration lane. For a full dev reset, see `docs/deployments.md` § Dev rollback runbook. |
|
|
273
|
+
| **Code** | [The git revert SHA, or the feature flag that disables the change] | `git revert {COMMIT}` |
|
|
274
|
+
| **Risk window** | [The gap between the DB migration merge and the code deploy] | [e.g., "~2 min deploy build, so the migration must be additive"] |
|
|
274
275
|
|
|
275
|
-
|
|
276
|
+
[**If** there are no DB changes → write "Code-only — `git revert` sufficient."]
|
|
276
277
|
|
|
277
278
|
## Agent Execution Runbook
|
|
278
279
|
|
|
279
|
-
[
|
|
280
|
+
[A chronological task checklist. Initially set to `PENDING`.]
|
|
280
281
|
|
|
281
282
|
**Implementation Tasks (Examples):**
|
|
282
283
|
|
|
283
284
|
<!-- bkit:group 1 start -->
|
|
284
285
|
|
|
285
|
-
### GROUP 1: [e.g., Item status in the API]
|
|
286
|
+
### TASK GROUP 1: [e.g., Item status in the API]
|
|
286
287
|
|
|
287
288
|
<!-- bkit:task 1 start -->
|
|
288
289
|
|
|
289
|
-
- [ ] **TASK 1:** [e.g., Create
|
|
290
|
-
- **CREATE:** `
|
|
291
|
-
- **DONE WHEN:** [e.g., the migration exists
|
|
292
|
-
- **TEST FIRST:** n/a — [e.g., migration
|
|
290
|
+
- [ ] **TASK 1:** [e.g., Create the database migration with the repo's migration script (`pnpm db:diff`)]
|
|
291
|
+
- **CREATE:** `packages/db/migrations/{timestamp}_add_items_status.sql`: [e.g., the `items.status` column]
|
|
292
|
+
- **DONE WHEN:** [e.g., the migration exists, and `pnpm db:reset` replays it cleanly]
|
|
293
|
+
- **TEST FIRST:** n/a — [e.g., a migration, covered by the fresh-DB replay tier]
|
|
293
294
|
|
|
294
295
|
<!-- bkit:task 1 end -->
|
|
295
296
|
|
|
296
297
|
<!-- bkit:task 2 start -->
|
|
297
298
|
|
|
298
|
-
- [ ] **TASK 2:** [e.g., Implement backend API action `setStatus`]
|
|
299
|
-
- **CREATE:** `setStatus` in `packages/api/src/items/setStatus.ts`: [e.g.,
|
|
299
|
+
- [ ] **TASK 2:** [e.g., Implement the backend API action `setStatus`]
|
|
300
|
+
- **CREATE:** `setStatus` in `packages/api/src/items/setStatus.ts`: [e.g., a validated status change]
|
|
300
301
|
- **READ:** `ItemStatus` in `packages/api/src/items/schema.ts`: [e.g., the allowed statuses]
|
|
301
302
|
- **DEPENDS ON:** 1
|
|
302
|
-
- **DONE WHEN:** [e.g., unit test covers each status transition
|
|
303
|
+
- **DONE WHEN:** [e.g., a unit test covers each status transition, and the integration test passes]
|
|
303
304
|
- **TEST FIRST:**
|
|
304
305
|
- `packages/api/src/items/setStatus.test.ts` `rejects an unknown status` fails on [e.g., an unknown status being accepted]
|
|
305
306
|
- `packages/api/items.integration.test.ts` `persists the new status` fails on [e.g., no row being stored]
|
|
@@ -310,43 +311,48 @@ _No DB changes: "Code-only — `git revert` sufficient."_
|
|
|
310
311
|
|
|
311
312
|
### 🔒 Gate 2: Code Implementation Check
|
|
312
313
|
|
|
313
|
-
- [ ] **No bolt-on
|
|
314
|
-
- [ ] **
|
|
315
|
-
- [ ] **
|
|
314
|
+
- [ ] **No bolt-on:** every `[NEW]` file traces to a `Reuse Inventory` `NEW` row.
|
|
315
|
+
- [ ] **Extensions landed:** every `EXTEND` landed in the artifact its row names.
|
|
316
|
+
- [ ] **No gate weakened:** no gate was weakened.
|
|
317
|
+
- [ ] **Red before code:** the tests step recorded every planned test of the group red, or as an `updated` existing test, before its code step ran.
|
|
318
|
+
- [ ] **Tests unchanged:** every planned test case matches the lines its red row recorded.
|
|
319
|
+
- [ ] **Unproven tests:** each planned test with no proven red is cleared only by a human-committed `TEST EXCEPTION` field.
|
|
320
|
+
- [ ] **Gate 2 — Verified:** every box above is checked.
|
|
316
321
|
|
|
317
322
|
**Mandatory Tasks (Testing & Documentation):**
|
|
318
323
|
|
|
319
|
-
- [ ] **Verify test coverage against Derived Test Matrix:** each row's test
|
|
320
|
-
- [ ] **Sweep existing tests:** broken tests fixed
|
|
321
|
-
- [ ] **Sweep new tests:** every task's `DONE WHEN`
|
|
322
|
-
- [ ] **Verify observability:** errors logged and traced
|
|
323
|
-
- [ ] **Update documentation:** affected docs rewritten to match.
|
|
324
|
+
- [ ] **Verify test coverage against Derived Test Matrix:** each row's test is in one task's `DONE WHEN`.
|
|
325
|
+
- [ ] **Sweep existing tests:** broken tests are fixed, and the full suite passes.
|
|
326
|
+
- [ ] **Sweep new tests:** every test a task's `DONE WHEN` names exists and passes.
|
|
327
|
+
- [ ] **Verify observability:** errors are logged and traced as `docs/observability.md` describes.
|
|
328
|
+
- [ ] **Update documentation:** the affected docs are rewritten to match.
|
|
324
329
|
|
|
325
330
|
### 🔒 Gate 3: Testing & Documentation Check
|
|
326
331
|
|
|
327
|
-
- [ ] **Docs updated:** every `Documentation Updates` row done
|
|
328
|
-
- [ ] **
|
|
332
|
+
- [ ] **Docs updated:** every `Documentation Updates` row is done.
|
|
333
|
+
- [ ] **Docs index accurate:** `.agents/docs.md` is accurate.
|
|
334
|
+
- [ ] **Gate 3 — Verified:** every box above is checked.
|
|
329
335
|
|
|
330
336
|
## Verification Plan
|
|
331
337
|
|
|
332
338
|
### Automated Tests
|
|
333
339
|
|
|
334
|
-
- [ ] **Full Local Gate Suite:** deepest declared `bkit:gate:*` script and `bkit check` pass.
|
|
335
|
-
- [ ] **Test Synchronization:** [
|
|
336
|
-
- [ ] **Build Configuration:** [
|
|
337
|
-
- [ ] **[Test Type] (`path/to/test.spec.ts`):** [
|
|
338
|
-
- [ ] **Apply local migrations:** [
|
|
339
|
-
- [ ] **Run all tests:** [
|
|
340
|
+
- [ ] **Full Local Gate Suite:** the deepest declared `bkit:gate:*` script and `bkit check` pass.
|
|
341
|
+
- [ ] **Test Synchronization:** [The existing E2E tests to update alongside.]
|
|
342
|
+
- [ ] **Build Configuration:** [How test-only files are kept out of the production build (e.g., the compiler config's exclude list).]
|
|
343
|
+
- [ ] **[Test Type] (`path/to/test.spec.ts`):** [The flow, unit or E2E additions, and their data hygiene needs.]
|
|
344
|
+
- [ ] **Apply local migrations:** [The new migrations applied locally (e.g., `pnpm db:reset`).]
|
|
345
|
+
- [ ] **Run all tests:** [The local unit and integration suites (e.g., `pnpm test`, `pnpm test:integration`) pass.]
|
|
340
346
|
|
|
341
347
|
### 🔒 Gate 4: Automated Verification Check
|
|
342
348
|
|
|
343
|
-
- [ ] **Gate 4
|
|
349
|
+
- [ ] **Gate 4 — Verified:** every Automated Tests box is checked, with proof (test output, a CLI result or an API response).
|
|
344
350
|
|
|
345
|
-
###
|
|
351
|
+
### Manual Verification
|
|
346
352
|
|
|
347
353
|
> [!CAUTION]
|
|
348
|
-
> **Owner-run acceptance checks
|
|
354
|
+
> **Owner-run acceptance checks, advisory only.** An unticked box blocks nothing: not the merge, and not plan approval. This is not a Gate 1 human-confirmation section.
|
|
349
355
|
|
|
350
|
-
- [ ] **Step 1:** [How to verify the feature end
|
|
356
|
+
- [ ] **Step 1:** [How to verify the feature end to end through the CLI or the database.]
|
|
351
357
|
|
|
352
358
|
<!-- bkit:end -->
|
|
@@ -6,7 +6,6 @@ import * as path from "node:path";
|
|
|
6
6
|
import { spawnSync } from "node:child_process";
|
|
7
7
|
import type { PreflightFinding } from "../before/index.js";
|
|
8
8
|
import { readJsonFile } from "../../shared/json.js";
|
|
9
|
-
import { readBkitConfig } from "../../shared/settings.js";
|
|
10
9
|
|
|
11
10
|
// ---------------------------------------------------------------------------
|
|
12
11
|
// Token-surface detectors
|
|
@@ -63,7 +62,7 @@ export function detectGhMcpToken(cwd: string): PreflightFinding | null {
|
|
|
63
62
|
detect:
|
|
64
63
|
"BKIT_GH_TOKEN is not set in the shell environment (undefined). The GitHub MCP server authenticates with `Authorization: Bearer ${BKIT_GH_TOKEN}` — without it, every tracker, PR, and board MCP call fails to connect.",
|
|
65
64
|
action:
|
|
66
|
-
"Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor
|
|
65
|
+
"Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor Cloud Agents / Codex Cloud) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
|
|
67
66
|
};
|
|
68
67
|
}
|
|
69
68
|
if (status === "empty") {
|
|
@@ -108,51 +107,55 @@ export function detectGhSecret(secretName: string): TokenPresence {
|
|
|
108
107
|
}
|
|
109
108
|
|
|
110
109
|
/**
|
|
111
|
-
* Build the consolidated
|
|
112
|
-
*
|
|
113
|
-
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
110
|
+
* Build the consolidated cloud-secrets checklist advisory. Fires when the consumer's
|
|
111
|
+
* repo has bkit-cloud.yml installed OR a `.claude/`, `.cursor/` or `.codex/` install
|
|
112
|
+
* present — each indicates cloud-side agent use. Lists one location per trigger present:
|
|
113
|
+
* GitHub Actions for the router, plus each installed host's cloud dashboard with its
|
|
114
|
+
* generated paste doc. Never depends on the issue tracker: every host's env block is the
|
|
115
|
+
* same tracker-independent set (install/cloud-env.ts).
|
|
116
116
|
*
|
|
117
|
-
* Returns null when none of the
|
|
117
|
+
* Returns null when none of the trigger paths exist.
|
|
118
118
|
*/
|
|
119
119
|
export function buildCloudDashboardsAdvisory(cwd: string): PreflightFinding | null {
|
|
120
120
|
const hasRouter = fs.existsSync(path.join(cwd, ".github", "workflows", "bkit-cloud.yml"));
|
|
121
|
-
const
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
121
|
+
const hosts: Array<[string, string]> = [
|
|
122
|
+
[
|
|
123
|
+
".cursor",
|
|
124
|
+
"**Cursor Cloud Agents**: open `https://cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab. Add each secret as a **Runtime Secret** (loaded as an env var, redacted from the agent's transcript). Cursor reads `.cursor/Dockerfile` + `.cursor/environment.json` from the repo but secrets come from this dashboard only; the resolved paste-ready values are in `.cursor/bkit-cloud.md` (gitignored).",
|
|
125
|
+
],
|
|
126
|
+
[
|
|
127
|
+
".claude",
|
|
128
|
+
"**Claude Code (web)**: open `https://claude.ai/code` → environment selector → your environment → **Environment variables**. Paste the block from `.claude/bkit-cloud.md` (gitignored), which also carries the setup script and network list. Claude reads both from the dashboard, NOT from the repo, so changes here do not require a commit.",
|
|
129
|
+
],
|
|
130
|
+
[
|
|
131
|
+
".codex",
|
|
132
|
+
"**Codex Cloud**: open ChatGPT → **Settings > Codex Cloud > Environments** → your environment → **Environment variables**. Paste the block from `.codex/bkit-cloud.md` (gitignored), which also carries the install script and allowed domains.",
|
|
133
|
+
],
|
|
134
|
+
];
|
|
135
|
+
const present = hosts.filter(([dir]) => fs.existsSync(path.join(cwd, dir)));
|
|
136
|
+
if (!hasRouter && present.length === 0) return null;
|
|
137
|
+
|
|
138
|
+
const sections: string[] = [];
|
|
139
|
+
if (hasRouter) {
|
|
140
|
+
sections.push(
|
|
141
|
+
"**GitHub Actions** (used by bkit-cloud.yml and your own workflows):\n" +
|
|
142
|
+
" gh secret set ANTHROPIC_API_KEY --body='<value>'\n\n" +
|
|
143
|
+
" Verify: `gh secret list | grep -E 'ANTHROPIC_API_KEY'`\n\n" +
|
|
144
|
+
" Keyless alternative for bkit-cloud.yml (workload identity federation): leave the secret unset and set the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables (`gh variable set`) from a Claude Console federation rule.\n\n" +
|
|
145
|
+
" ANTHROPIC_API_KEY is read from the Anthropic dashboard (https://console.anthropic.com/settings/keys); `.bkit/.env` holds the same value as BKIT_ANTHROPIC_API_KEY. The Claude GitHub App (`/install-github-app`) is also required for `cloud=claude`.",
|
|
146
|
+
);
|
|
147
|
+
}
|
|
148
|
+
for (const [, text] of present) sections.push(text);
|
|
143
149
|
return {
|
|
144
150
|
id: "cloud-secrets-three-locations",
|
|
145
151
|
severity: "advisory",
|
|
146
|
-
detect:
|
|
152
|
+
detect:
|
|
153
|
+
"The secrets bkit's cloud integration uses must also be set in each cloud location you use. Bkit cannot verify dashboard state — surface the checklist so you don't ship a half-configured cloud setup.",
|
|
147
154
|
action:
|
|
148
155
|
"Set each secret in the required locations:\n\n" +
|
|
149
|
-
|
|
150
|
-
ghSetLines +
|
|
151
|
-
"2. **Cursor Cloud Agents** (used by Cursor's cloud agent runner): open `https://cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab. Add each secret as a **Runtime Secret** (loaded as an env var, redacted from the agent's transcript). Cursor reads `.cursor/Dockerfile` + `.cursor/environment.json` from the repo but secrets come from this dashboard only; the resolved paste-ready values are in `.cursor/bkit-cloud.md` (gitignored).\n\n" +
|
|
152
|
-
"3. **Claude Code (web)** (used by Claude.ai's cloud agent runner): open `https://claude.ai/code` → Settings → Setup → Environment Variables. Add each secret. Claude reads its setup script from the dashboard, NOT from the repo, so changes here do not require a commit.\n\n" +
|
|
156
|
+
sections.map((s, i) => `${i + 1}. ${s}\n\n`).join("") +
|
|
153
157
|
"**Context-fetch (`/bkit-debug` in the cloud):** if you run the debug workflow in these cloud agents, the observability creds your `.agents/context.md` context-fetch blocks use (e.g. `VERCEL_TOKEN`, `SUPABASE_ACCESS_TOKEN`) must ALSO be set in the same dashboards above — non-interactively, since headless agents cannot `vercel login`. These are operator/observability READ creds, not app-runtime secrets. Commit the non-secret selectors (team scope / project ref / `--environment`) in your copied block so they need no dashboard entry. The CLIs those blocks call install automatically in the cloud from each block's `context-fetch:provision` sibling — no manual setup.\n\n" +
|
|
154
|
-
"Same VALUE in all places.
|
|
155
|
-
vendorNote,
|
|
158
|
+
"Same VALUE in all places.",
|
|
156
159
|
};
|
|
157
160
|
}
|
|
158
161
|
|