@cbartens/bkit 6.1.0 → 6.2.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 +14 -12
- package/.bkit/core/.agents/docs.md +1 -11
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
- package/.bkit/core/.agents/rules.md +22 -9
- package/.bkit/core/.bkit/README.md +13 -11
- package/.bkit/core/.bkit/authoring.md +58 -13
- package/.bkit/core/.bkit/cli.md +43 -33
- package/.bkit/core/.bkit/cloud.md +93 -30
- package/.bkit/core/.bkit/install.md +55 -16
- package/.bkit/core/.bkit/jsonl.md +24 -7
- package/.bkit/core/.bkit/pipeline.md +8 -8
- package/.bkit/core/.bkit/prompts.md +160 -43
- package/.bkit/core/.bkit/providers.md +99 -36
- package/.bkit/core/.bkit/templates.md +167 -37
- package/.bkit/core/.bkit/trackers.md +39 -6
- package/.bkit/core/.bkit/workflows.md +344 -136
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
- package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
- package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/docs/templates/bkit-plan.md +38 -8
- package/.bkit/core/engine/checks/after/auth.ts +118 -47
- package/.bkit/core/engine/checks/after/github.ts +161 -37
- package/.bkit/core/engine/checks/after/index.ts +18 -3
- package/.bkit/core/engine/checks/after/tools.ts +245 -1
- package/.bkit/core/engine/checks/before/files.ts +59 -1
- package/.bkit/core/engine/checks/before/index.ts +8 -0
- package/.bkit/core/engine/checks/status-holes.ts +20 -26
- package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
- package/.bkit/core/engine/checks/tips/detect.ts +36 -3
- package/.bkit/core/engine/checks/tips/index.ts +1 -1
- package/.bkit/core/engine/cli.ts +13 -13
- package/.bkit/core/engine/commands/ci/ci.ts +124 -19
- package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
- package/.bkit/core/engine/commands/install/doctor.ts +5 -5
- package/.bkit/core/engine/commands/install/install.ts +28 -25
- package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
- package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
- package/.bkit/core/engine/commands/land.ts +2 -3
- package/.bkit/core/engine/commands/lib.ts +394 -39
- package/.bkit/core/engine/commands/registry.ts +1 -1
- package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
- package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
- package/.bkit/core/engine/commands/workflow/context.ts +71 -10
- package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
- package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
- package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
- package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
- package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
- package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
- package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
- package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
- package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
- package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
- package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
- package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
- package/.bkit/core/engine/commands/workflow/status.ts +324 -11
- package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
- package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
- package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
- package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
- package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
- package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
- package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
- package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
- package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
- package/.bkit/core/engine/install/cloud-env.ts +38 -10
- package/.bkit/core/engine/install/managed-block.ts +105 -0
- package/.bkit/core/engine/install/manifest.ts +7 -1
- package/.bkit/core/engine/install/modules/claude.ts +6 -2
- package/.bkit/core/engine/install/modules/cloud.ts +84 -95
- package/.bkit/core/engine/install/modules/codex.ts +10 -2
- package/.bkit/core/engine/install/modules/core.ts +202 -26
- package/.bkit/core/engine/install/modules/opencode.ts +18 -23
- package/.bkit/core/engine/install/network-allowlist.ts +8 -3
- package/.bkit/core/engine/install/project-docs.ts +650 -0
- package/.bkit/core/engine/install/template-copies.ts +58 -5
- package/.bkit/core/engine/install/write.ts +128 -7
- package/.bkit/core/engine/ledgers/journal.ts +18 -10
- package/.bkit/core/engine/ledgers/migrate.ts +20 -8
- package/.bkit/core/engine/ledgers/status.ts +604 -8
- package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
- package/.bkit/core/engine/render/trackers.ts +46 -11
- package/.bkit/core/engine/shared/package-manager.ts +7 -3
- package/.bkit/core/engine/shared/settings.ts +12 -1
- package/.bkit/core/engine/shared/text.ts +14 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
- package/.bkit/core/engine/tools/instructions.ts +116 -20
- package/.bkit/core/hooks/antigravity-hook.js +20 -4
- package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
- package/.bkit/core/hooks/gateguard-engine.js +249 -23
- package/.bkit/core/hooks/guardrails-deny.js +167 -0
- package/.bkit/core/hooks/guardrails-read.js +3 -3
- package/.bkit/core/hooks/guardrails-shell.js +1122 -167
- package/.bkit/core/hooks/guardrails-tiers.js +247 -176
- package/.bkit/core/hooks/preflight-tracker.sh +219 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
- package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
- package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
- package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
- package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
- package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
- package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
- package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
- package/.bkit/core/prompts/bkit-design-generate.md +6 -4
- package/.bkit/core/prompts/bkit-design-organise.md +4 -3
- package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
- package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
- package/.bkit/core/prompts/bkit-design-spike.md +4 -3
- package/.bkit/core/prompts/bkit-design-update.md +6 -4
- package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
- package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
- package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
- package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
- package/.bkit/core/prompts/bkit-plan-update.md +22 -8
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
- package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
- package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
- package/.bkit/core/workflows/bkit-auto.md +23 -11
- package/.bkit/core/workflows/bkit-build.md +331 -100
- package/.bkit/core/workflows/bkit-debug.md +135 -64
- package/.bkit/core/workflows/bkit-design.md +58 -32
- package/.bkit/core/workflows/bkit-plan.md +73 -45
- package/.bkit/core/workflows/bkit-ship.md +233 -167
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
- package/.bkit/shared/.bkit/.env.example +5 -0
- package/.bkit/shared/.claude/bkit-cloud.md +7 -7
- package/.bkit/shared/.claude/settings.json +5 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
- package/.bkit/shared/.cursor/hooks.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
- package/.bkit/templates/.cursor/Dockerfile +7 -7
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
- package/.bkit/templates/.github/dependabot.yml +5 -0
- package/.bkit/templates/.github/renovate.json5 +5 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
- package/.bkit/templates/.husky/pre-push +123 -6
- package/.bkit/templates/context/bkit-serena.md +1 -1
- package/.bkit/templates/context/bkit-vercel.md +103 -59
- package/.bkit/templates/docs/architecture.md +98 -0
- package/.bkit/templates/docs/capabilities.md +33 -37
- package/.bkit/templates/docs/components.md +142 -0
- package/.bkit/templates/docs/data-schema.md +87 -0
- package/.bkit/{shared → templates}/docs/deployments.md +128 -142
- package/.bkit/templates/docs/design.md +117 -0
- package/.bkit/templates/docs/noise.md +54 -0
- package/.bkit/templates/docs/observability.md +99 -0
- package/.bkit/templates/docs/security.md +137 -0
- package/.bkit/templates/docs/setup.md +93 -0
- package/.bkit/templates/docs/technology.md +70 -0
- package/.bkit/{shared → templates}/docs/testing.md +200 -87
- package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
- package/.bkit/templates/slop-scan.config.json +2 -0
- package/CHANGELOG.md +79 -0
- package/DETAILS.md +661 -0
- package/README.md +73 -604
- package/dist/checks/after/auth.js +114 -46
- package/dist/checks/after/github.js +138 -35
- package/dist/checks/after/index.js +16 -4
- package/dist/checks/after/tools.js +224 -1
- package/dist/checks/before/files.js +59 -1
- package/dist/checks/before/index.js +7 -1
- package/dist/checks/status-holes.js +20 -21
- package/dist/checks/tips/catalogue.js +99 -10
- package/dist/checks/tips/detect.js +35 -3
- package/dist/checks/tips/index.js +1 -1
- package/dist/cli.js +13 -13
- package/dist/commands/ci/ci.js +113 -20
- package/dist/commands/ci/push-gate.js +79 -44
- package/dist/commands/install/doctor.js +5 -5
- package/dist/commands/install/install.js +23 -22
- package/dist/commands/install/uninstall.js +36 -30
- package/dist/commands/install/upgrade.js +10 -2
- package/dist/commands/land.js +2 -3
- package/dist/commands/lib.js +323 -25
- package/dist/commands/workflow/branches.js +312 -72
- package/dist/commands/workflow/challenge.js +66 -13
- package/dist/commands/workflow/context.js +46 -10
- package/dist/commands/workflow/counters.js +231 -23
- package/dist/commands/workflow/decisions.js +221 -106
- package/dist/commands/workflow/disk.js +2 -1
- package/dist/commands/workflow/feature-base.js +60 -0
- package/dist/commands/workflow/issues.js +243 -15
- package/dist/commands/workflow/junit.js +137 -0
- package/dist/commands/workflow/ledgers.js +726 -112
- package/dist/commands/workflow/locks.js +150 -29
- package/dist/commands/workflow/loops.js +67 -0
- package/dist/commands/workflow/open-decision.js +199 -0
- package/dist/commands/workflow/plan-blocks.js +6 -0
- package/dist/commands/workflow/plans.js +1 -1
- package/dist/commands/workflow/prs.js +272 -16
- package/dist/commands/workflow/repo.js +1 -1
- package/dist/commands/workflow/run-facts.js +6 -0
- package/dist/commands/workflow/runs.js +747 -155
- package/dist/commands/workflow/runtime.js +8 -4
- package/dist/commands/workflow/status.js +259 -13
- package/dist/commands/workflow/step-table.js +41 -15
- package/dist/commands/workflow/steps.js +530 -26
- package/dist/commands/workflow/summary-findings.js +1 -1
- package/dist/commands/workflow/summary.js +289 -8
- package/dist/commands/workflow/tasks.js +294 -27
- package/dist/commands/workflow/tests-base.js +266 -0
- package/dist/commands/workflow/tests-changed.js +130 -56
- package/dist/commands/workflow/tests-jump.js +77 -0
- package/dist/commands/workflow/tests.js +608 -131
- package/dist/commands/workflow/tracker.js +920 -112
- package/dist/commands/workflow/workflows.js +80 -59
- package/dist/commands/workflow/worktrees.js +387 -58
- package/dist/install/cloud-env.js +32 -10
- package/dist/install/managed-block.js +101 -0
- package/dist/install/manifest.js +7 -1
- package/dist/install/modules/claude.js +6 -2
- package/dist/install/modules/cloud.js +73 -86
- package/dist/install/modules/codex.js +9 -2
- package/dist/install/modules/core.js +190 -27
- package/dist/install/modules/opencode.js +18 -23
- package/dist/install/network-allowlist.js +8 -3
- package/dist/install/project-docs.js +551 -0
- package/dist/install/template-copies.js +55 -5
- package/dist/install/write.js +117 -5
- package/dist/ledgers/journal.js +10 -8
- package/dist/ledgers/migrate.js +20 -9
- package/dist/ledgers/status.js +461 -8
- package/dist/ledgers/telemetry.js +71 -13
- package/dist/render/trackers.js +21 -12
- package/dist/shared/package-manager.js +7 -2
- package/dist/shared/settings.js +8 -0
- package/dist/shared/text.js +13 -0
- package/dist/tools/instructions-sources.js +1 -0
- package/dist/tools/instructions.js +97 -24
- package/package.json +23 -15
- package/.bkit/core/hooks/preflight-linear.sh +0 -73
- package/.bkit/shared/docs/architecture.md +0 -16
- package/.bkit/shared/docs/data-schema.md +0 -16
- package/.bkit/shared/docs/design.md +0 -38
- package/.bkit/shared/docs/noise.md +0 -20
- package/.bkit/shared/docs/observability.md +0 -22
- package/.bkit/shared/docs/security.md +0 -62
- package/.bkit/shared/docs/setup.md +0 -52
- package/.bkit/shared/docs/technology.md +0 -15
- /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
- /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
package/.bkit/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# bkit — Agent Workflow System
|
|
2
2
|
|
|
3
|
-
<!-- bkit:managed v6.
|
|
3
|
+
<!-- bkit:managed v6.2.0 — do not edit; run `bkit upgrade` to refresh -->
|
|
4
4
|
|
|
5
5
|
> [!CAUTION]
|
|
6
6
|
> **Purpose:** What bkit does, the environment and tracker setup, the upgrade paste, the ongoing CLI and the friction-sharing paste. First-time install and the full auth setup are in `.bkit/install.md`. Workflow internals are in `.bkit/workflows.md`, and subagent metadata (effort, model, tools, `maxTurns`) is in `.bkit/prompts.md`.
|
|
@@ -29,7 +29,7 @@ Here is a typical cycle for `ISSUE-123` "Add feature X":
|
|
|
29
29
|
- Runs `direnv allow` when the worktree's `.envrc` matches the main checkout's.
|
|
30
30
|
- Runs `pnpm install --frozen-lockfile`, unless `bkit.workflows.worktree.install: false`.
|
|
31
31
|
5. **Phase steps** — the workflow dispatches subagents: `@bkit-plan-generate`, then `@bkit-plan-review-1`, `-2` and `@bkit-plan-scope-check` in parallel, and so on. Each one writes to `docs/plans/{YYYYMM}/logs/{FID}/`. The orchestrator posts each completed step as a new tracker comment. `{YYYYMM}` is the canonical month bucket, taken at design start.
|
|
32
|
-
6. **Phase summary** — `bkit workflows summary` writes the summary from the run's status rows, with a verdict (`PASS` / `CONCERNS` / `FAIL`). The workflow commits it as `chore(issue-123-…): summary bkit [skip ci]` for design / plan, or as `chore(issue-123-…): summary` for build/debug/ship, and
|
|
32
|
+
6. **Phase summary** — `bkit workflows summary` writes the summary from the run's status rows, with a verdict (`PASS` / `CONCERNS` / `FAIL`). The workflow commits it as `chore(issue-123-…): summary bkit [skip ci]` for design / plan, or as `chore(issue-123-…): summary` for build/debug/ship. Build and debug push it in the same step, ship pushes it with its bookkeeping, and design and plan land it when the run closes.
|
|
33
33
|
7. **Close Workflow** — the tracker issue moves to `In Review`, and the phase label stays. `/bkit-design` / `/bkit-plan` prune the worktree and delete `feat/issue-123-…`, which is merged into `dev`. `/bkit-build` / `/bkit-debug` keep the worktree.
|
|
34
34
|
8. **Human review** — the design / plan sits at its canonical path, `docs/plans/{YYYYMM}/{FID}-{design,plan}.md`. The reviewer re-triggers the workflow or moves on to `/bkit-build`.
|
|
35
35
|
9. **`/bkit-build`** — re-creates the worktree and executes the plan test-first: a tests agent writes each group's planned tests, the engine proves them failing, and a separate code agent makes them pass. It runs the deepest declared local gate, including integration when declared, and opens a PR to `dev`.
|
|
@@ -51,9 +51,9 @@ Plans are sized by `bkit.workflows.tasks` in `package.json`. Each group holds up
|
|
|
51
51
|
| --- | --- | --- | --- | --- |
|
|
52
52
|
| Design | `/bkit-design` | 12 | `docs/plans/{YYYYMM}/{FID}-design.md` | Yes — review before plan |
|
|
53
53
|
| Plan | `/bkit-plan` | 8 | `docs/plans/{YYYYMM}/{FID}-plan.md` | Yes — review before build |
|
|
54
|
-
| Build | `/bkit-build` |
|
|
54
|
+
| Build | `/bkit-build` | 16 | PR to `dev` | No — CI continues |
|
|
55
55
|
| Debug | `/bkit-debug` | 11 | Remediation commit on feature branch | No |
|
|
56
|
-
| Ship | `/bkit-ship` |
|
|
56
|
+
| Ship | `/bkit-ship` | 12 | Squash-merged PR, issue `In Review` + `bkit:merged` (plans stay canonical at `docs/plans/{YYYYMM}/`) | Yes |
|
|
57
57
|
|
|
58
58
|
**Where an issue starts.** The issue body and its comments are every workflow's first input. Issue shapes and the lines a machine reads are in `.bkit/trackers.md` § Issue shapes, and example forms are in `.bkit/templates.md` § Issue forms.
|
|
59
59
|
|
|
@@ -262,11 +262,11 @@ bkit owns some files outright, owns one part of others, and ships the rest as te
|
|
|
262
262
|
| Kind | Semantics | Files |
|
|
263
263
|
| --- | --- | --- |
|
|
264
264
|
| **Tier 1 — Fully managed** | Idempotent rewrite of whole file on every install. A consumer edit is overwritten. Uninstall deletes the file while it still matches the hash bkit recorded. | `.bkit/*.md` (except `prompts.md`, Tier 2), `.bkit/.env.example`, `.bkit/allowlist.json`, `.cursor/cli.json` |
|
|
265
|
-
| **Tier 2 — Managed-block** | bkit owns content between `bkit:start`/`bkit:end` markers. Consumer owns everything outside. File absent → write whole file. File present without markers → append block at EOF, unless the markdown file already holds an older unmarked copy of the block (its `# ` title plus 10+ long lines verbatim) → warn + skip. A full uninstall strips the block and deletes a file left with nothing else; `docs/templates/bkit-*.md` are bkit's whole and are deleted. | `docs/*.md`, `docs/templates/bkit-*.md`, `.gitignore`, `.agents/rules.md`, `.agents/context.md`, `.agents/docs.md`, `.agents/skills.md`, `AGENTS.md`, `CLAUDE.md`, `.claude/hooks/bkit-preflight.sh`, `.cursor/hooks/bkit-preflight.sh`, `.claude/hooks/bkit-gateguard.cjs`, `.cursor/hooks/bkit-gateguard.cjs`, `.opencode/plugin/bkit-gateguard.js`, `.cursor/hooks/bkit-guardrails.cjs`, `.codex/hooks/bkit-gateguard.cjs`, `.codex/hooks/bkit-guardrails.cjs` |
|
|
265
|
+
| **Tier 2 — Managed-block** | bkit owns content between `bkit:start`/`bkit:end` markers. Consumer owns everything outside. File absent → write whole file. File present without markers → append block at EOF, unless the markdown file already holds an older unmarked copy of the block (its `# ` title plus 10+ long lines verbatim) → warn + skip. A full uninstall strips the block and deletes a file left with nothing else; `docs/templates/bkit-*.md` are bkit's whole and are deleted. | `docs/*.md`, `docs/templates/bkit-*.md`, `.gitignore`, `.agents/rules.md`, `.agents/context.md`, `.agents/docs.md`, `.agents/skills.md`, `AGENTS.md`, `CLAUDE.md`, `.claude/hooks/bkit-preflight.sh`, `.cursor/hooks/bkit-preflight.sh`, `.claude/hooks/bkit-gateguard.cjs`, `.cursor/hooks/bkit-gateguard.cjs`, `.opencode/plugin/bkit-gateguard.js`, `.claude/hooks/bkit-guardrails.cjs`, `.cursor/hooks/bkit-guardrails.cjs`, `.codex/hooks/bkit-gateguard.cjs`, `.codex/hooks/bkit-guardrails.cjs`, `.agents/plugins/bkit/hooks/bkit-guardrails.cjs`, `.opencode/plugin/bkit-guardrails.js` |
|
|
266
266
|
| **Shared JSON** | bkit owns the keys its template sets; every other key is yours. `.mcp.json` / `.cursor/mcp.json`: bkit owns exactly one entry, `mcpServers.<tracker>`, and resets it to the template on every install and upgrade. | `.claude/settings.json`, `.cursor/hooks.json`, `.opencode/opencode.json`, `.mcp.json`, `.cursor/mcp.json` |
|
|
267
267
|
| **Seeded package.json scripts** | Every install and upgrade adds a missing name with bkit's default; a name already present is never touched, whatever its value. `bkit check` reports a missing name. Uninstall leaves them. | `scripts.bkit:gate:format` / `bkit:gate:static` / `bkit:gate:static-unit` / `bkit:gate:install-static-unit-build` / `bkit:deps:outdated` / `bkit:deps:audit` |
|
|
268
268
|
| **Seeded bkit settings** | Every install and upgrade writes every `bkit` setting, so each one is visible where you look for it. A missing key gets its default; a choice not made yet (tracker, cloud agents, board, OpenCode provider) gets `""` or `[]`, which reads the same as absent. A key already present is never touched, whatever its value; nested blocks get their missing keys. `bkit check` reports a missing key. | every key under `bkit`: `SEEDED_BKIT_DEFAULTS` in `.bkit/core/engine/install/modules/core.ts` |
|
|
269
|
-
| **Templates** | Never written into your repo. Install and upgrade copy them, raw, into `.bkit/templates/`; you copy what you want and own it. Catalog: `.bkit/templates.md`. | `.github/workflows/bkit-ci.yml`, `.github/workflows/bkit-cloud.yml`, `.husky/*`, `.vale.ini`, `.vale/styles/Bkit/*`,
|
|
269
|
+
| **Templates** | Never written into your repo. Install and upgrade copy them, raw, into `.bkit/templates/`; you copy what you want and own it. Catalog: `.bkit/templates.md`. | `.github/workflows/bkit-ci.yml`, `.github/workflows/bkit-cloud.yml`, `.husky/*`, `.vale.ini`, `.vale/styles/Bkit/*`, `lintstagedrc.example.json`, `slop-scan.config.json`, `.oxlintrc.json`, `prettierignore.example`, `.envrc`, `.cursor/{settings.json,environment.json,Dockerfile}`, dependency-updater examples, `.github/workflows/bkit-trivy.yml`, the per-provider context-fetch blocks (`context/bkit-*.md`), `scripts/slop/bkit-slop-type-suppression.mjs`. Also the tool `package.json` scripts (`typecheck`, `lint`, `format:check`, `bkit:lint:prose`, `lint:slop`, `bkit:slop:delta`, `prepare`) and devDeps (prettier, slop-scan, lint-staged, husky): `.bkit/templates.md` lists them, install never adds them. |
|
|
270
270
|
|
|
271
271
|
**Marker syntax** depends on the file format:
|
|
272
272
|
|
|
@@ -278,7 +278,7 @@ Block updates keep the comment prefixes (`# `, `// `) before the markers.
|
|
|
278
278
|
|
|
279
279
|
**Managed-version marker.** Every non-JSON file bkit writes carries `bkit:managed vX.Y.Z` in its comment syntax, as the first line inside the `bkit:start` block or near the top of a whole file: `<!-- … -->` (markdown), `# <!-- … -->` (shell, `.gitignore`, `.gitattributes`, `.env.example`, TOML), `// …` (JS). The full MIT text and copyright notice travel at `.bkit/LICENSE.md`. Install and upgrade restamp the marker. `bkit check` reports `bkit-managed-stale` for a marker that differs from the installed version: a blocker on `main` / `dev`, and an advisory on feature branches. Templates carry no marker and no block.
|
|
280
280
|
|
|
281
|
-
**Hook scripts.** Install generates each host's `bkit-preflight.sh`, `gateguard`, `readguard`, `guardrails` and `rules` hook from its template plus the code the hosts share (`.bkit/core/hooks/`, `.bkit/providers.md` § Hooks). bkit's block in the `bkit-gateguard` / `bkit-readguard` / `bkit-rules` hooks and plugins and the
|
|
281
|
+
**Hook scripts.** Install generates each host's `bkit-preflight.sh`, `gateguard`, `readguard`, `guardrails` and `rules` hook from its template plus the code the hosts share (`.bkit/core/hooks/`, `.bkit/providers.md` § Hooks). bkit's block in the `bkit-gateguard` / `bkit-readguard` / `bkit-rules` / `bkit-guardrails` hooks and plugins is a pure engine: it advises, and the guardrails block also returns a refusal for the shell deny tier for the driver to act on. It reads no stdin, writes no stdout and makes no top-level call, so it cannot collide with a consumer's own emitter. Delivery differs by host. Claude / Codex / Cursor inject the checklist before the edit. OpenCode appends it to the tool result in `execute.after` (`BKIT_GATEGUARD=deny` is the only pre-edit block). The rules-read advisory rides the two `bkit-preflight.sh` hooks at session start and the `bkit-rules` hook at the first tool call. See `.bkit/providers.md` § Hooks. A consumer file with no markers gets the block appended. Wire its exported function into your driver.
|
|
282
282
|
|
|
283
283
|
### What install writes
|
|
284
284
|
|
|
@@ -291,7 +291,7 @@ Block updates keep the comment prefixes (`# `, `// `) before the markers.
|
|
|
291
291
|
| `.gitignore` | core | `.bkit/shared/gitignore` | Tier 2 html-comment |
|
|
292
292
|
| `AGENTS.md` | core | `.bkit/core/AGENTS.md` | Tier 2 html-comment |
|
|
293
293
|
| `CLAUDE.md` | claude | `.bkit/shared/CLAUDE.md` | Tier 2 html-comment |
|
|
294
|
-
| `docs
|
|
294
|
+
| `docs/{architecture,technology,security,data-schema,testing,deployments,observability,design,noise,setup}.md` | project | starters in `.bkit/templates/docs/` | Never written by install or upgrade. Copy a starter into `docs/` and add its row to `Project Documents` in `.agents/docs.md`; install and upgrade register present documents, and remove the ownership wrapper from a copy an older release installed. |
|
|
295
295
|
| `docs/templates/bkit-*.md` | core | `.bkit/core/docs/templates/` | Tier 2 html-comment |
|
|
296
296
|
| `.gitattributes` | core | `.bkit/shared/.gitattributes` | Tier 2 html-comment (`merge=union` for the append-only ledgers) |
|
|
297
297
|
| `.bkit/templates/**` | — | the whole `.bkit/templates/` root | Raw copies, refreshed on every install and upgrade; never hashed. Upgrade prints the changed paths. |
|
|
@@ -303,6 +303,7 @@ Block updates keep the comment prefixes (`# `, `// `) before the markers.
|
|
|
303
303
|
| `.claude/hooks/bkit-preflight.sh` | claude | `.bkit/core/.claude/hooks/` | Tier 2 html-comment (`# ` prefix) |
|
|
304
304
|
| `.claude/hooks/bkit-gateguard.cjs` | claude | `.bkit/core/.claude/hooks/` | Tier 2 slash-comment |
|
|
305
305
|
| `.claude/hooks/bkit-readguard.cjs` | claude | `.bkit/core/.claude/hooks/` | Tier 2 slash-comment. Repeat-read advisory. |
|
|
306
|
+
| `.claude/hooks/bkit-guardrails.cjs` | claude | `.bkit/core/.claude/hooks/` | Tier 2 slash-comment. Refuses the shell deny tier; advises on curl / wget hosts and shell edits. |
|
|
306
307
|
| `.mcp.json` | claude | `.bkit/shared/.mcp.json` | Shared JSON: bkit owns `mcpServers.<tracker>` only; absent file → the tracker-filtered render |
|
|
307
308
|
| `.bkit/.env.example` | claude | `.bkit/shared/.bkit/.env.example` | Tier 1 (fully managed). Real values go in `.bkit/.env`. |
|
|
308
309
|
| `.cursor/commands/bkit-*.md` | cursor | `.bkit/core/workflows/` (T1+T2 transforms) | Host pass — always overwrite |
|
|
@@ -322,6 +323,7 @@ Block updates keep the comment prefixes (`# `, `// `) before the markers.
|
|
|
322
323
|
| `.opencode/commands/bkit-*.md` | OpenCode | `.bkit/core/workflows/` | Host pass — always overwrite |
|
|
323
324
|
| `.opencode/agents/bkit-*.md` | OpenCode | `.bkit/core/prompts/` | Host pass — always overwrite |
|
|
324
325
|
| `.opencode/plugin/bkit-gateguard.js` | OpenCode | `.bkit/core/.opencode/plugin/` | Tier 2 slash-comment |
|
|
326
|
+
| `.opencode/plugin/bkit-guardrails.js` | OpenCode | `.bkit/core/.opencode/plugin/` | Tier 2 slash-comment. Refuses the shell deny tier. |
|
|
325
327
|
| `.opencode/plugin/bkit-readguard.js` | OpenCode | `.bkit/core/.opencode/plugin/` | Tier 2 slash-comment. Repeat-read advisory. |
|
|
326
328
|
| `.claude/hooks/bkit-cloud-bootstrap.sh` | — | `.bkit/templates/.claude/hooks/` | Copy-and-own template: no module writes it; adopt it from `.bkit/templates/` (the SessionStart entry runs it only when present). |
|
|
327
329
|
|
|
@@ -329,7 +331,7 @@ The cloud workflow and the Cursor Background Agent files are templates the `--au
|
|
|
329
331
|
|
|
330
332
|
### Optional post-install decisions (tracker + cloud agents)
|
|
331
333
|
|
|
332
|
-
Two capabilities are opt-in and left out of the default install: the **issue tracker** (`--tracker=github|linear|jira`) and **cloud agents** (`--auto=claude|cursor
|
|
334
|
+
Two capabilities are opt-in and left out of the default install: the **issue tracker** (`--tracker=github|linear|jira`) and **cloud agents** (`--auto=claude|opencode|codex|cursor`). The default install ships zero cloud footprint. While a choice is undecided, its advisory fires (`tracker-setup-none` / `cloud-router-none`). Setting `"none"` in `bkit.tracker.default` / `bkit.cloud.agent` silences it. The dependency updater, security scan and test lint are copy-and-own templates. The choices, the defaults and how to decide are in `.bkit/install.md` § Optional post-install decisions. The template catalog is in `.bkit/templates.md`.
|
|
333
335
|
|
|
334
336
|
### Updater PRs against your workflows
|
|
335
337
|
|
|
@@ -339,7 +341,7 @@ Two capabilities are opt-in and left out of the default install: the **issue tra
|
|
|
339
341
|
|
|
340
342
|
## Triggering workflows
|
|
341
343
|
|
|
342
|
-
|
|
344
|
+
Three paths exist: a Linear comment (cloud), Claude (interactive, local) and Cursor (interactive, local). All three run the same workflow from `.bkit/core/workflows/`. The compute source and the orchestrator model differ.
|
|
343
345
|
|
|
344
346
|
### From a tracker comment (cloud — Cursor Cloud Agent)
|
|
345
347
|
|
|
@@ -355,7 +357,7 @@ There are three paths: a Linear comment (cloud), Claude (interactive, local) and
|
|
|
355
357
|
|
|
356
358
|
**GitHub tracker:** a PR label triggers the run, through the Cursor Automations trigger "Pull request label changed". `bkit:auto` on the PR (from `bkit-build`) triggers dispatch, and the phase label (`bkit:plan`, `bkit:build`, etc.) selects the workflow. Issue comments go through the GitHub MCP. `/bkit-design` / `/bkit-plan` have no PR, so with the GitHub tracker they are local-IDE-only on Cursor cloud.
|
|
357
359
|
|
|
358
|
-
**Requirements (Linear):** the `
|
|
360
|
+
**Requirements (Linear):** the `bkit:auto` label and a state that is not finished (judged by state category). `BKIT_LINEAR_API_KEY`, `BKIT_CURSOR_API_KEY`, `BKIT_ANTHROPIC_API_KEY` and `BKIT_GH_TOKEN` in the Cursor Cloud Agent dashboard.
|
|
359
361
|
|
|
360
362
|
**Requirements (GitHub):** `BKIT_GH_TOKEN`, `BKIT_CURSOR_API_KEY` and `BKIT_ANTHROPIC_API_KEY` in the dashboard. The Cursor GitHub App on the repo/org. `GITHUB_ISSUE_ID` comes from the PR body's `<!-- bkit:issue=#NNN -->`, with no manual setup.
|
|
361
363
|
|
|
@@ -378,7 +380,7 @@ Claude reads the issue, its comments and the plan files through the tracker MCP.
|
|
|
378
380
|
|
|
379
381
|
**Manual batch of held builds:** merge the held `feat/{FID}` branches into one branch off `dev` yourself, push it and open one PR. You own the push, the PR, the CI gate, the sweep and the docs sync. One head commit means post-merge auto-debug sees only the last FID. Never batch migrations.
|
|
380
382
|
|
|
381
|
-
**Requirements:** `BKIT_GH_TOKEN` and an active Claude session (subscription or `BKIT_ANTHROPIC_API_KEY`). `BKIT_LINEAR_API_KEY` as well when `bkit.tracker.default = "linear"`, and `BKIT_JIRA_API_KEY` when it is `"jira"`. The session model is the orchestrator pin in `.bkit/prompts.md` § Orchestrators (`Claude` column). Set it with `/model` before you invoke a command. This file does not repeat the pin.
|
|
383
|
+
**Requirements:** `BKIT_GH_TOKEN` and an active Claude session (subscription or `BKIT_ANTHROPIC_API_KEY`). `BKIT_LINEAR_API_KEY` as well when `bkit.tracker.default = "linear"`, and `BKIT_JIRA_API_KEY` when it is `"jira"`. A session that carries an issue id (`GITHUB_ISSUE_ID`) is guarded: it stops when the issue lost `bkit:auto` or is finished, on GitHub, Linear and Jira. A session with no issue id is unguarded. The session model is the orchestrator pin in `.bkit/prompts.md` § Orchestrators (`Claude` column). Set it with `/model` before you invoke a command. This file does not repeat the pin.
|
|
382
384
|
|
|
383
385
|
### From Cursor (interactive — local)
|
|
384
386
|
|
|
@@ -32,15 +32,6 @@
|
|
|
32
32
|
| `.bkit/router.md` | — | — | — | — | — | `bkit-{command}` workflow router — picks the workflow and each host's command file. |
|
|
33
33
|
| `.agents/skills.md` | ○ | ○ | ● | ○ | ○ | Permanent skill registry, installation checks and activation boundaries. |
|
|
34
34
|
| `.agents/context.md` | ○ | ○ | ○ | ● | ○ | How to reach information outside repo — deployment logs, CI runs, e2e evidence, web search, cloud egress allowlist, CLI provisioning. |
|
|
35
|
-
| `docs/architecture.md` | ● | ● | ● | ○ | ○ | System design — service boundaries, deployment topology, integration sketch. |
|
|
36
|
-
| `docs/technology.md` | ● | ● | ○ | ○ | ○ | Chosen frameworks, libraries, styling systems, coding conventions. Why a choice was made goes in `decisions.jsonl`. |
|
|
37
|
-
| `docs/data-schema.md` | ○ | ○ | ● | ○ | ○ | Active production database schema — entities / tables, fields, access policies (e.g. RLS), indices, functions, triggers. |
|
|
38
|
-
| `docs/security.md` | ● | ● | ● | ○ | ○ | Authentication, authorization, input validation, rate limiting, secrets management, PII handling, untrusted-content threat model and skill-guidance boundary. |
|
|
39
|
-
| `docs/design.md` | ○ | ○ | ○ | — | — | Design system — palette, typography, components, spacing, a11y, layout tokens. |
|
|
40
|
-
| `docs/testing.md` | ○ | ● | ● | ● | — | Testing strategy — tier boundaries, framework choices, naming conventions, CI lane graph (names, needs, when a lane runs). |
|
|
41
|
-
| `docs/deployments.md` | ○ | ○ | ○ | ● | ● | Deployment / CI/CD — secrets, branch protection, one-run concurrency, push base, promote after the capstone. |
|
|
42
|
-
| `docs/observability.md` | ○ | ○ | ● | ● | ○ | Logging architecture, correlation tracing, telemetry pipelines, log drains. |
|
|
43
|
-
| `docs/noise.md` | — | — | ○ | ● | ○ | Registry of intentional signal downgrades — log levels, error-tracker archives / mutes, alert thresholds. |
|
|
44
35
|
| `docs/decisions.jsonl` | ● | ● | ○ | ○ | ○ | ADRs — what was decided, why, discarded alternatives. Append-only. |
|
|
45
36
|
| `docs/knowledge.jsonl` | ○ | ● | ● | ● | ○ | Lessons, traps, post-mortems, gotchas (symptom → root cause → fix). Append-only. |
|
|
46
37
|
| `docs/failures.jsonl` | ○ | ○ | ○ | ○ | ○ | Ledger of discovered bugs. Append-only. |
|
|
@@ -53,9 +44,8 @@
|
|
|
53
44
|
| `docs/templates/bkit-audit-*.md` | — | ○ | — | — | — | Audit templates. Use with `@bkit-audit-generate` to generate reports. |
|
|
54
45
|
| `.bkit/jsonl.md` | ○ | ○ | ○ | ○ | ○ | Row format for the `*.jsonl` ledgers — envelope, per-kind fields, dedup tuples, write idiom. |
|
|
55
46
|
| `.bkit/authoring.md` | ○ | ○ | ○ | ○ | ○ | Authoring rules for agent-read markdown — docs, prompts, workflows; punctuation and capitals. |
|
|
56
|
-
| `docs/setup.md` | — | — | — | — | — | Local dev — CLIs, configuration, secrets, troubleshooting. Humans only. |
|
|
57
47
|
|
|
58
|
-
> `Project Documents` below `bkit:end` belongs to the project, so `bkit install` never overwrites it and `bkit check` reports no drift for it. Add project-specific docs there.
|
|
48
|
+
> `Project Documents` below `bkit:end` belongs to the project, so `bkit install` never overwrites it and `bkit check` reports no drift for it. Add project-specific docs there. The ten recommended project documents (`docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/data-schema.md`, `docs/testing.md`, `docs/deployments.md`, `docs/observability.md`, `docs/design.md`, `docs/noise.md`, `docs/setup.md`) start as copies of `.bkit/templates/docs/`. Copy one into `docs/` and add its row there; an indexed document at another path stands in for its topic when its Scope names the recommended path (`Equivalent to docs/security.md`). Fill them in the order in `.bkit/templates.md` § Project docs — adoption order.
|
|
59
49
|
|
|
60
50
|
<!-- bkit:end -->
|
|
61
51
|
|
|
@@ -43,7 +43,13 @@ const crypto = require("node:crypto");
|
|
|
43
43
|
|
|
44
44
|
// Antigravity's file-writing tools. `write_to_file` creates or overwrites a whole file;
|
|
45
45
|
// `replace_file_content` edits in place. `Edit` / `Write` are accepted as matchers too.
|
|
46
|
-
const EDIT_TOOLS = new Set([
|
|
46
|
+
const EDIT_TOOLS = new Set([
|
|
47
|
+
"write_to_file",
|
|
48
|
+
"replace_file_content",
|
|
49
|
+
"multi_replace_file_content",
|
|
50
|
+
"Edit",
|
|
51
|
+
"Write",
|
|
52
|
+
]);
|
|
47
53
|
|
|
48
54
|
// Antigravity names the touched path `TargetFile`; `file_path` / `path` / `target_file`
|
|
49
55
|
// cover a consumer's own matcher. Resolved against cwd.
|
|
@@ -69,14 +75,29 @@ function bkitGateguard(payload) {
|
|
|
69
75
|
const input = p.tool_input || {};
|
|
70
76
|
const cwd = typeof p.cwd === "string" ? p.cwd : "";
|
|
71
77
|
const sessionId = dedupKey(p.session_id, p.agent_id);
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
const
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
78
|
+
// Prepare every unwarned target (nothing recorded), select complete blocks inside the
|
|
79
|
+
// budget, and acknowledge them only once the deny-once transport has delivered them.
|
|
80
|
+
const blocks = [];
|
|
81
|
+
const seen = new Set();
|
|
82
|
+
for (const t of parseEditTargets(input, cwd)) {
|
|
83
|
+
// A write_to_file to a not-yet-existing path is a NEW file and gets the reuse
|
|
84
|
+
// checklist; the replace tools always edit an existing file in place.
|
|
85
|
+
const isNew = p.tool_name === "write_to_file" && !fs.existsSync(t.file);
|
|
86
|
+
const prepared = prepareAdvice(t.file, sessionId, isNew, cwd);
|
|
87
|
+
if (!prepared || seen.has(prepared.key)) continue;
|
|
88
|
+
seen.add(prepared.key);
|
|
89
|
+
blocks.push(prepared);
|
|
90
|
+
}
|
|
91
|
+
if (blocks.length === 0) return null;
|
|
92
|
+
const { selected, context } = selectAdvice(blocks, ADVICE_BUDGETS.antigravity);
|
|
93
|
+
const sent = adviseOnceDelivery(
|
|
94
|
+
"gateguard",
|
|
95
|
+
sessionId,
|
|
96
|
+
agCallSignature(p.tool_name, input),
|
|
97
|
+
context,
|
|
98
|
+
);
|
|
99
|
+
if (sent.delivered) acknowledgeSelected(selected);
|
|
100
|
+
return sent.decision;
|
|
80
101
|
}
|
|
81
102
|
|
|
82
103
|
// bkit:end
|
|
@@ -42,8 +42,12 @@ const os = require("node:os");
|
|
|
42
42
|
const path = require("node:path");
|
|
43
43
|
const crypto = require("node:crypto");
|
|
44
44
|
|
|
45
|
+
// {{BKIT_PART gateguard-engine.js}}
|
|
46
|
+
|
|
45
47
|
// {{BKIT_PART guardrails-shell.js}}
|
|
46
48
|
|
|
49
|
+
// {{BKIT_PART guardrails-deny.js}}
|
|
50
|
+
|
|
47
51
|
// {{BKIT_PART guardrails-tiers.js}}
|
|
48
52
|
|
|
49
53
|
// {{BKIT_PART guardrails-read.js}}
|
|
@@ -90,37 +94,31 @@ function bkitGuardrails(payload) {
|
|
|
90
94
|
const input = p.tool_input || {};
|
|
91
95
|
if (READ_TOOL_NAMES.has(tool)) return decideRead(input.AbsolutePath ?? input.file_path);
|
|
92
96
|
if (!SHELL_TOOL_NAMES.has(tool)) return null;
|
|
93
|
-
const raw =
|
|
94
|
-
? input.command.join(" ")
|
|
95
|
-
: (input.CommandLine ?? input.command);
|
|
97
|
+
const raw = shellCommandText(input.CommandLine ?? input.command);
|
|
96
98
|
if (typeof raw !== "string") return null;
|
|
97
99
|
|
|
98
100
|
const cmd = raw.trim();
|
|
99
|
-
const
|
|
101
|
+
const ctx = hookContext(p);
|
|
102
|
+
const tier = classifyShell(cmd, "antigravity", ctx);
|
|
100
103
|
if (!tier) return null;
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
const advisory =
|
|
120
|
-
tier.tier === "fetch"
|
|
121
|
-
? `bkit Antigravity guardrails: outbound fetch to a host that is not on the network allowlist.\nConfirm the destination is intended before you rely on the result.\nCommand: ${cmd}`
|
|
122
|
-
: shellEditAdvisory(tier.edits);
|
|
123
|
-
return adviseOnce("guardrails", p.session_id, agCallSignature(tool, input), advisory);
|
|
104
|
+
const hold = tier.tier !== "deny" && tier.tier !== "ask" && tier.tier !== "secret";
|
|
105
|
+
const advice = composeAdvice(tier, "antigravity", ADVICE_BUDGETS.antigravity, {
|
|
106
|
+
command: cmd,
|
|
107
|
+
ctx,
|
|
108
|
+
session: p.session_id,
|
|
109
|
+
agent: p.agent_id,
|
|
110
|
+
// The retry text the hold-once delivery appends counts against the budget.
|
|
111
|
+
reserve: hold ? adviceSize(AG_RETRY_SUFFIX, ADVICE_BUDGETS.antigravity.unit) : 0,
|
|
112
|
+
});
|
|
113
|
+
if (!hold) return { decision: tier.tier === "deny" ? "deny" : "ask", reason: advice.text };
|
|
114
|
+
const sent = adviseOnceDelivery(
|
|
115
|
+
"guardrails",
|
|
116
|
+
p.session_id,
|
|
117
|
+
agCallSignature(tool, input),
|
|
118
|
+
advice.text,
|
|
119
|
+
);
|
|
120
|
+
if (sent.delivered) acknowledgeSelected(advice.selected);
|
|
121
|
+
return sent.decision;
|
|
124
122
|
}
|
|
125
123
|
|
|
126
124
|
// bkit:end
|
|
@@ -12,6 +12,7 @@
|
|
|
12
12
|
> - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit this file.
|
|
13
13
|
> - `Universal Rules` apply to all agents; `Orchestrator Rules` apply only to workflows and commands.
|
|
14
14
|
> - Local project rules / overrides → `Project Rules` below the bkit-managed block; universal rules stay in the block.
|
|
15
|
+
> - What the project optimises for → `Project Goals`, between `Project Rules` and `Project Settings`. Goals break ties between options the rules both allow, and add no rule.
|
|
15
16
|
> - Where project services live (repo, boards, service org / project ids) → `Project Settings`, the last section. It holds facts only: no rules, and nothing that changes workflows, gates or permissions.
|
|
16
17
|
|
|
17
18
|
## bkit Rules
|
|
@@ -44,19 +45,19 @@
|
|
|
44
45
|
- **Narrow text search first:** Run `grep -l` / `rg -l` with path and file-type filters first, then `grep -n -m {N}` on the matched files. Do not run a broad recursive grep that returns full match lists.
|
|
45
46
|
- **Code reads:** Locate first (language server, else text search), then read only the line range you need (the file-read tool's offset and limit, or `sed -n 'A,Bp'`). Read a whole file only when it is short or you will rewrite it. Do not re-read a file unchanged since your last read, unless the context was summarised since.
|
|
46
47
|
- **Command output:** Request structured, bounded output from CLIs, APIs and SQL (`--json` plus limit flags, SQL `LIMIT`, `jq` field selection), and filter at the source (time window, environment, issue ID). Do not re-run a fetch whose output is already in context.
|
|
47
|
-
- **New files:** Put each new file where `docs/architecture.md` places its kind. When
|
|
48
|
+
- **New files:** Put each new file where `docs/architecture.md` places its kind. When that document is present and does not place that kind, add the kind there in the same change and say why; if it is missing, warn and follow the nearest existing structure.
|
|
48
49
|
- **File edits:** Use the fastest tool: an edit for a surgical change, a write for a new file, and an append where possible.
|
|
49
|
-
- **Edit tools:** Change file contents with the edit and write tools, not with shell commands that hand-edit source files or get around pre-edit gates. Exceptions: files generated by scripts, bulk mechanical rewrites, and appending a log line to your own step output file with `>>`.
|
|
50
|
+
- **Edit tools:** Change file contents with the edit and write tools, not with shell commands that hand-edit source files or get around pre-edit gates. Exceptions: files generated by scripts, bulk mechanical rewrites, and appending a log line to your own step output file with `>>`. An exception waives the edit tool, never the authoring reads: follow `.bkit/authoring.md` before the edit.
|
|
50
51
|
- **Dead code:** Comments explain what, not why. Do not narrate the diff or leave placeholders, commented-out code or dead stubs. Match the surrounding comment density.
|
|
51
52
|
- **Tmp files:** Put temporary files in the repo-root `tmp/`, not the system `/tmp/` or `/private/tmp`.
|
|
52
53
|
- **CI edits:** Any change to `.github/workflows/*` MUST have human confirmation first; do not edit those files unprompted.
|
|
53
|
-
- **UI design:** Build every user interface to `docs/design.md
|
|
54
|
+
- **UI design:** Build every user interface to `docs/design.md` when it is present and the change touches UI; if it is missing or still the starter, warn and follow the existing UI conventions.
|
|
54
55
|
- **Dependencies:** Declare every package the code uses, and keep the dependency manifest and its lockfile in sync (e.g. `package.json` and `pnpm-lock.yaml`).
|
|
55
56
|
|
|
56
57
|
#### Documentation
|
|
57
58
|
|
|
58
59
|
- **Keep current:** Update the affected docs in the same change as the code they describe, not as a follow-up. Doc drift is a regression.
|
|
59
|
-
- **Authoring:** Follow `.bkit/authoring.md` § All Agent-Read Files when you write or edit an agent-read file, plus § Docs for a doc, and follow each doc's `Rules` header.
|
|
60
|
+
- **Authoring:** Follow `.bkit/authoring.md` § All Agent-Read Files when you write or edit an agent-read file, plus § Docs for a doc and § Doc Templates for a template, and follow each doc's `Rules` header.
|
|
60
61
|
- **Format:** Write plain, complete sentences that keep their grammar words (articles, plurals), and cut filler, hedges and repetition. Prefer tables to prose, and bullets to paragraphs.
|
|
61
62
|
|
|
62
63
|
#### Agent Management
|
|
@@ -74,13 +75,14 @@
|
|
|
74
75
|
- **Deferred work:** Record each deferral instead of dropping it silently: append one row per deferral to `docs/deferrals.jsonl` with `bkit ledgers append` (`.bkit/jsonl.md` § Write Idiom), reusing the `key` of any existing entry for the same item. Every row MUST carry a `reason` from the closed enum; a deferral with no valid reason is not a deferral, so finish the work.
|
|
75
76
|
- **Discovered bugs:** Record each discovered bug instead of dropping it silently: append one row per bug to `docs/failures.jsonl` with `bkit ledgers append` (`.bkit/jsonl.md` § Write Idiom), reusing the `key` of any existing entry for the same item.
|
|
76
77
|
- **Flaky tests:** For each test that passes only on retry or fails intermittently, append one row per test to `docs/failures.jsonl` with `bkit ledgers append` (`.bkit/jsonl.md` § Write Idiom), reusing the `key` of any existing entry for the same item.
|
|
78
|
+
- **Discovered gotchas:** Record each discovered gotcha instead of dropping it silently: append one row per gotcha to `docs/knowledge.jsonl` with `bkit ledgers append` (`.bkit/jsonl.md` § Write Idiom), reusing the `key` of any existing entry for the same item.
|
|
77
79
|
- **Tracker issue creation:** Suggest issues instead of creating them, and create one ONLY after explicit human confirmation; write the body per `.bkit/trackers.md` § Issue shapes.
|
|
78
80
|
- **Tracker issue settings:** Keep the title to at most 70 characters, or two lines on mobile. Set labels, project, project status, priority, size, milestone, parent, and every open blocking issue as blocked-by. Set priority and size per `docs/templates/bkit-audit-issues.md` § Ranking Rules and § Size Scale, not by label alone. Blocked-by MUST use the machine-read form per `.bkit/trackers.md` § Issue shapes, not prose alone. Check similar issues when unclear.
|
|
79
81
|
- **Tracker next labels:** An issue without a workflow label MUST carry exactly one of the `next:design|next:plan|next:build|next:debug|next:ship` labels. Do not put a `next:*` label alongside a workflow label. Standing audit parents are excepted.
|
|
80
82
|
- **Tracker workflow labels:** Add one of the `bkit:design|bkit:plan|bkit:build|bkit:debug|bkit:ship` labels only when the issue starts that workflow. They are mutually exclusive: the next workflow start drops the previous one, and the `/bkit-ship` close swaps `bkit:ship` → `bkit:merged`. To signal intent, use a `next:*` label, not a workflow label added by hand.
|
|
81
83
|
- **Tracker failure label:** On any workflow Failure Path, add `bkit:failed` alongside the workflow label.
|
|
82
84
|
- **Tracker issue mentions:** Mention an issue ID only together with its title and URL.
|
|
83
|
-
- **Tracker work comments:** For any issue worked on outside `/bkit-*` workflows, post one comment per related issue at the end of every major turn (files changed, commit, PR, finding or blocked stop) with the work done, the outcome and links. Skip turns with no work (Q&A, clarifying questions). Describe the change instead of pasting diffs or restating code, and do not mention @claude or @cursor in the comment body.
|
|
85
|
+
- **Tracker work comments:** For any issue worked on outside `/bkit-*` workflows, post one comment per related issue at the end of every major turn (files changed, commit, PR, finding or blocked stop) with the work done, the outcome and links. Post it as plain markdown with the tracker MCP's comment tool, never through `bkit issues comment`, which is for workflow steps only, and never start it with a `###### bkit:generated` line, because workflows drop every comment that starts with one. Skip turns with no work (Q&A, clarifying questions). Describe the change instead of pasting diffs or restating code, and do not mention @claude or @cursor in the comment body.
|
|
84
86
|
- **Tracker context cut:** Put `###### bkit:ignore-earlier` on its own line in an issue body or comment to drop all earlier content from workflow inputs. Without it, earlier content stays, and the newer text wins where two disagree. Add the marker ONLY with human confirmation, never unprompted in any output.
|
|
85
87
|
- **Tracker MCPs:** Do tracker reads / writes via `bkit` verbs; use the configured tracker MCP only when a verb prints `tracker.done: false` or exits 80.
|
|
86
88
|
|
|
@@ -113,13 +115,14 @@
|
|
|
113
115
|
- **Reproduce first:** Fix a reported failure only once you can reproduce it: add a failing test and see it fail (red) before touching code. This rule covers failure remediation; build tasks follow the plan's `TEST FIRST` (red → green).
|
|
114
116
|
- **No downgrades:** Do not fix a failure by downgrading; **STOP** if stuck.
|
|
115
117
|
- **Fix code not gates:** Make gates (anything a `bkit:gate:*` script runs) pass by fixing root causes, not by weakening them: no type-system escapes (e.g. TS `as any`, `as unknown as`, `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`; Python `# type: ignore`), linter disables (e.g. `eslint-disable`, `//nolint`), test skips (e.g. `.skip`, `xfail`), deleted assertions, error-swallowing, empty catches, or mocking away the units under test. A config change that is genuinely warranted is ONLY a targeted per-file / per-rule opt-out, made after explicit human confirmation. Inside `/bkit-*` workflows, where confirmation is unavailable, record the block per your own blocker contract and continue, without authorising the opt-out yourself.
|
|
116
|
-
- **
|
|
118
|
+
- **Recovery precedence:** Apply a command's explicit recovery route and its limit first. Correct and retry at most twice per scope only after a rejection that the engine reports as guaranteed no-write (effects = none, correctable = true); reconcile an uncertain effect before any retry. A recovered command error alone does not enter Failure Path; an exhausted budget, a failing check, missing authorization or an unsafe recovery does, and recovery never weakens a test, bypasses a gate or grants approval.
|
|
119
|
+
- **Check gotchas first:** Before touching code, fold the `docs/knowledge.jsonl` ledger by `key`, highest `ts` wins → read only the winning rows where `status` is `ACTIVE` or absent; the engine does the fold, so run `bkit ledgers query --ledger=knowledge --status=ACTIVE` instead of reading the file (an agent without a shell reads the query output its caller names under **Read**).
|
|
117
120
|
- **External context first:** Read `.agents/context.md` before concluding anything about runtime behaviour, CI, or external / upstream causes.
|
|
118
121
|
- **Provider data:** For logs, errors and the database, prefer the enabled `.agents/context.md` context-fetch blocks or the provider's CLI over MCP.
|
|
119
122
|
- **Cloud setup gaps:** In a cloud session, read `.bkit/.unavailable` first when it exists. Each line names a provision recipe that failed setup, and the reason, so treat what it provides as absent: do not retry its install, and name it wherever it leaves a check not run.
|
|
120
|
-
- **Local tests first:**
|
|
123
|
+
- **Local tests first:** Run only the tests the change affects and a targeted repro before remote CI; the full suite runs only in the pre-push hook. **If** a deployed-boundary / `@live` failure cannot be reproduced locally → review existing evidence first.
|
|
121
124
|
- **Existing evidence first:** Search and read existing reports, logs and artifacts before requesting a new remote CI run; request one only when the existing evidence is insufficient, stale or absent.
|
|
122
|
-
- **Local pre-commit:** Before a commit, run only the tests the change affects (tests importing changed code or naming a changed file's path)
|
|
125
|
+
- **Local pre-commit:** Before a commit and while working, run only the tests the change affects (tests importing changed code or naming a changed file's path), naming each test file, never a folder, a pattern, the full suite or a `bkit:gate:*` script, and run static checks on changed files. A `/bkit-*` step's named command is the only wider run.
|
|
123
126
|
- **Local pre-push:** Run nothing by hand before a push; the pre-push hook runs the gates. **If** the hook is not installed → run them by hand.
|
|
124
127
|
- **CI on PR to `dev` / `main`:** **If** the repo has adopted bkit's CI workflow template → static, unit, integration (incl. service / DB-backed) and E2E lanes, plus an always-on migration lane in repos with migrations (replay when planned), run as parallel lanes plus a `bkit-tests-check` capstone. E2E `needs:` the migration lane when that lane owns remote migration apply. No `@live` tests.
|
|
125
128
|
- **CI on push to `dev` / `main`:** **If** the repo has adopted bkit's CI workflow template → the PR lanes, plus remote migration apply inside the migration lane and the `@live` canary (both wait on migration != failure).
|
|
@@ -133,7 +136,7 @@
|
|
|
133
136
|
- **Shared local stack:** Worktrees share every local service with a fixed name or port (Docker database, emulator), so start, reset, stop and test against those services only through the repo's locked scripts (`.bkit/templates.md` § Machine lock); NEVER run the raw CLI (e.g. `supabase db reset`, `docker compose down`). A fix hint that prints a raw command is a bug.
|
|
134
137
|
- **Tests discriminate:** Assert on the surface the behaviour changes, so the test fails when the behaviour breaks. Do not assert only a transport status (e.g. HTTP 200) or a proxy surface, and do not mock away the boundary under test.
|
|
135
138
|
- **Test-only files:** Keep mocks and test configs out of the production build (e.g. a `tsconfig.json` `exclude`).
|
|
136
|
-
- **Explicit logging:** Automatic capture (e.g. log drains, change-data capture) does not replace explicit logs. Log each edge case it misses with the project's structured logger, per `docs/observability.md
|
|
139
|
+
- **Explicit logging:** Automatic capture (e.g. log drains, change-data capture) does not replace explicit logs. Log each edge case it misses with the project's structured logger, per `docs/observability.md` when it is present; if it is missing, warn and follow the project's existing logging conventions.
|
|
137
140
|
- **CLIs over dashboards:** Check CI, deploy and provider state with local CLIs (e.g. `gh`), not by asking the user to look at a dashboard.
|
|
138
141
|
|
|
139
142
|
#### Security & Data
|
|
@@ -178,6 +181,16 @@
|
|
|
178
181
|
|
|
179
182
|
### Orchestrator Rules
|
|
180
183
|
|
|
184
|
+
## Project Goals
|
|
185
|
+
|
|
186
|
+
What this project optimises for, most important first. Goals break ties: when two options both satisfy the rules, pick the one that serves these goals better. One bullet per goal; delete unused examples.
|
|
187
|
+
|
|
188
|
+
<!-- Examples:
|
|
189
|
+
- **Correct over fast:** A wrong answer costs more than a slow one. Prefer the option that checks its input.
|
|
190
|
+
- **Works for everyone:** Every screen works with a keyboard and a screen reader. Prefer the option that keeps it so.
|
|
191
|
+
- **Small to run:** Prefer the option with fewer moving parts to deploy and watch.
|
|
192
|
+
-->
|
|
193
|
+
|
|
181
194
|
## Project Settings
|
|
182
195
|
|
|
183
196
|
Non-secret identifiers agents pass to MCP servers and CLIs; tokens stay in env files. One row per value; delete unused rows.
|
|
@@ -29,7 +29,7 @@ Here is a typical cycle for `ISSUE-123` "Add feature X":
|
|
|
29
29
|
- Runs `direnv allow` when the worktree's `.envrc` matches the main checkout's.
|
|
30
30
|
- Runs `pnpm install --frozen-lockfile`, unless `bkit.workflows.worktree.install: false`.
|
|
31
31
|
5. **Phase steps** — the workflow dispatches subagents: `@bkit-plan-generate`, then `@bkit-plan-review-1`, `-2` and `@bkit-plan-scope-check` in parallel, and so on. Each one writes to `docs/plans/{YYYYMM}/logs/{FID}/`. The orchestrator posts each completed step as a new tracker comment. `{YYYYMM}` is the canonical month bucket, taken at design start.
|
|
32
|
-
6. **Phase summary** — `bkit workflows summary` writes the summary from the run's status rows, with a verdict (`PASS` / `CONCERNS` / `FAIL`). The workflow commits it as `chore(issue-123-…): summary bkit [skip ci]` for design / plan, or as `chore(issue-123-…): summary` for build/debug/ship, and
|
|
32
|
+
6. **Phase summary** — `bkit workflows summary` writes the summary from the run's status rows, with a verdict (`PASS` / `CONCERNS` / `FAIL`). The workflow commits it as `chore(issue-123-…): summary bkit [skip ci]` for design / plan, or as `chore(issue-123-…): summary` for build/debug/ship. Build and debug push it in the same step, ship pushes it with its bookkeeping, and design and plan land it when the run closes.
|
|
33
33
|
7. **Close Workflow** — the tracker issue moves to `In Review`, and the phase label stays. `/bkit-design` / `/bkit-plan` prune the worktree and delete `feat/issue-123-…`, which is merged into `dev`. `/bkit-build` / `/bkit-debug` keep the worktree.
|
|
34
34
|
8. **Human review** — the design / plan sits at its canonical path, `docs/plans/{YYYYMM}/{FID}-{design,plan}.md`. The reviewer re-triggers the workflow or moves on to `/bkit-build`.
|
|
35
35
|
9. **`/bkit-build`** — re-creates the worktree and executes the plan test-first: a tests agent writes each group's planned tests, the engine proves them failing, and a separate code agent makes them pass. It runs the deepest declared local gate, including integration when declared, and opens a PR to `dev`.
|
|
@@ -51,9 +51,9 @@ Plans are sized by `bkit.workflows.tasks` in `package.json`. Each group holds up
|
|
|
51
51
|
| --- | --- | --- | --- | --- |
|
|
52
52
|
| Design | `/bkit-design` | 12 | `docs/plans/{YYYYMM}/{FID}-design.md` | Yes — review before plan |
|
|
53
53
|
| Plan | `/bkit-plan` | 8 | `docs/plans/{YYYYMM}/{FID}-plan.md` | Yes — review before build |
|
|
54
|
-
| Build | `/bkit-build` |
|
|
54
|
+
| Build | `/bkit-build` | 16 | PR to `dev` | No — CI continues |
|
|
55
55
|
| Debug | `/bkit-debug` | 11 | Remediation commit on feature branch | No |
|
|
56
|
-
| Ship | `/bkit-ship` |
|
|
56
|
+
| Ship | `/bkit-ship` | 12 | Squash-merged PR, issue `In Review` + `bkit:merged` (plans stay canonical at `docs/plans/{YYYYMM}/`) | Yes |
|
|
57
57
|
|
|
58
58
|
**Where an issue starts.** The issue body and its comments are every workflow's first input. Issue shapes and the lines a machine reads are in `.bkit/trackers.md` § Issue shapes, and example forms are in `.bkit/templates.md` § Issue forms.
|
|
59
59
|
|
|
@@ -262,11 +262,11 @@ bkit owns some files outright, owns one part of others, and ships the rest as te
|
|
|
262
262
|
| Kind | Semantics | Files |
|
|
263
263
|
| --- | --- | --- |
|
|
264
264
|
| **Tier 1 — Fully managed** | Idempotent rewrite of whole file on every install. A consumer edit is overwritten. Uninstall deletes the file while it still matches the hash bkit recorded. | `.bkit/*.md` (except `prompts.md`, Tier 2), `.bkit/.env.example`, `.bkit/allowlist.json`, `.cursor/cli.json` |
|
|
265
|
-
| **Tier 2 — Managed-block** | bkit owns content between `bkit:start`/`bkit:end` markers. Consumer owns everything outside. File absent → write whole file. File present without markers → append block at EOF, unless the markdown file already holds an older unmarked copy of the block (its `# ` title plus 10+ long lines verbatim) → warn + skip. A full uninstall strips the block and deletes a file left with nothing else; `docs/templates/bkit-*.md` are bkit's whole and are deleted. | `docs/*.md`, `docs/templates/bkit-*.md`, `.gitignore`, `.agents/rules.md`, `.agents/context.md`, `.agents/docs.md`, `.agents/skills.md`, `AGENTS.md`, `CLAUDE.md`, `.claude/hooks/bkit-preflight.sh`, `.cursor/hooks/bkit-preflight.sh`, `.claude/hooks/bkit-gateguard.cjs`, `.cursor/hooks/bkit-gateguard.cjs`, `.opencode/plugin/bkit-gateguard.js`, `.cursor/hooks/bkit-guardrails.cjs`, `.codex/hooks/bkit-gateguard.cjs`, `.codex/hooks/bkit-guardrails.cjs` |
|
|
265
|
+
| **Tier 2 — Managed-block** | bkit owns content between `bkit:start`/`bkit:end` markers. Consumer owns everything outside. File absent → write whole file. File present without markers → append block at EOF, unless the markdown file already holds an older unmarked copy of the block (its `# ` title plus 10+ long lines verbatim) → warn + skip. A full uninstall strips the block and deletes a file left with nothing else; `docs/templates/bkit-*.md` are bkit's whole and are deleted. | `docs/*.md`, `docs/templates/bkit-*.md`, `.gitignore`, `.agents/rules.md`, `.agents/context.md`, `.agents/docs.md`, `.agents/skills.md`, `AGENTS.md`, `CLAUDE.md`, `.claude/hooks/bkit-preflight.sh`, `.cursor/hooks/bkit-preflight.sh`, `.claude/hooks/bkit-gateguard.cjs`, `.cursor/hooks/bkit-gateguard.cjs`, `.opencode/plugin/bkit-gateguard.js`, `.claude/hooks/bkit-guardrails.cjs`, `.cursor/hooks/bkit-guardrails.cjs`, `.codex/hooks/bkit-gateguard.cjs`, `.codex/hooks/bkit-guardrails.cjs`, `.agents/plugins/bkit/hooks/bkit-guardrails.cjs`, `.opencode/plugin/bkit-guardrails.js` |
|
|
266
266
|
| **Shared JSON** | bkit owns the keys its template sets; every other key is yours. `.mcp.json` / `.cursor/mcp.json`: bkit owns exactly one entry, `mcpServers.<tracker>`, and resets it to the template on every install and upgrade. | `.claude/settings.json`, `.cursor/hooks.json`, `.opencode/opencode.json`, `.mcp.json`, `.cursor/mcp.json` |
|
|
267
267
|
| **Seeded package.json scripts** | Every install and upgrade adds a missing name with bkit's default; a name already present is never touched, whatever its value. `bkit check` reports a missing name. Uninstall leaves them. | `scripts.bkit:gate:format` / `bkit:gate:static` / `bkit:gate:static-unit` / `bkit:gate:install-static-unit-build` / `bkit:deps:outdated` / `bkit:deps:audit` |
|
|
268
268
|
| **Seeded bkit settings** | Every install and upgrade writes every `bkit` setting, so each one is visible where you look for it. A missing key gets its default; a choice not made yet (tracker, cloud agents, board, OpenCode provider) gets `""` or `[]`, which reads the same as absent. A key already present is never touched, whatever its value; nested blocks get their missing keys. `bkit check` reports a missing key. | every key under `bkit`: `SEEDED_BKIT_DEFAULTS` in `.bkit/core/engine/install/modules/core.ts` |
|
|
269
|
-
| **Templates** | Never written into your repo. Install and upgrade copy them, raw, into `.bkit/templates/`; you copy what you want and own it. Catalog: `.bkit/templates.md`. | `.github/workflows/bkit-ci.yml`, `.github/workflows/bkit-cloud.yml`, `.husky/*`, `.vale.ini`, `.vale/styles/Bkit/*`,
|
|
269
|
+
| **Templates** | Never written into your repo. Install and upgrade copy them, raw, into `.bkit/templates/`; you copy what you want and own it. Catalog: `.bkit/templates.md`. | `.github/workflows/bkit-ci.yml`, `.github/workflows/bkit-cloud.yml`, `.husky/*`, `.vale.ini`, `.vale/styles/Bkit/*`, `lintstagedrc.example.json`, `slop-scan.config.json`, `.oxlintrc.json`, `prettierignore.example`, `.envrc`, `.cursor/{settings.json,environment.json,Dockerfile}`, dependency-updater examples, `.github/workflows/bkit-trivy.yml`, the per-provider context-fetch blocks (`context/bkit-*.md`), `scripts/slop/bkit-slop-type-suppression.mjs`. Also the tool `package.json` scripts (`typecheck`, `lint`, `format:check`, `bkit:lint:prose`, `lint:slop`, `bkit:slop:delta`, `prepare`) and devDeps (prettier, slop-scan, lint-staged, husky): `.bkit/templates.md` lists them, install never adds them. |
|
|
270
270
|
|
|
271
271
|
**Marker syntax** depends on the file format:
|
|
272
272
|
|
|
@@ -278,7 +278,7 @@ Block updates keep the comment prefixes (`# `, `// `) before the markers.
|
|
|
278
278
|
|
|
279
279
|
**Managed-version marker.** Every non-JSON file bkit writes carries `bkit:managed vX.Y.Z` in its comment syntax, as the first line inside the `bkit:start` block or near the top of a whole file: `<!-- … -->` (markdown), `# <!-- … -->` (shell, `.gitignore`, `.gitattributes`, `.env.example`, TOML), `// …` (JS). The full MIT text and copyright notice travel at `.bkit/LICENSE.md`. Install and upgrade restamp the marker. `bkit check` reports `bkit-managed-stale` for a marker that differs from the installed version: a blocker on `main` / `dev`, and an advisory on feature branches. Templates carry no marker and no block.
|
|
280
280
|
|
|
281
|
-
**Hook scripts.** Install generates each host's `bkit-preflight.sh`, `gateguard`, `readguard`, `guardrails` and `rules` hook from its template plus the code the hosts share (`.bkit/core/hooks/`, `.bkit/providers.md` § Hooks). bkit's block in the `bkit-gateguard` / `bkit-readguard` / `bkit-rules` hooks and plugins and the
|
|
281
|
+
**Hook scripts.** Install generates each host's `bkit-preflight.sh`, `gateguard`, `readguard`, `guardrails` and `rules` hook from its template plus the code the hosts share (`.bkit/core/hooks/`, `.bkit/providers.md` § Hooks). bkit's block in the `bkit-gateguard` / `bkit-readguard` / `bkit-rules` / `bkit-guardrails` hooks and plugins is a pure engine: it advises, and the guardrails block also returns a refusal for the shell deny tier for the driver to act on. It reads no stdin, writes no stdout and makes no top-level call, so it cannot collide with a consumer's own emitter. Delivery differs by host. Claude / Codex / Cursor inject the checklist before the edit. OpenCode appends it to the tool result in `execute.after` (`BKIT_GATEGUARD=deny` is the only pre-edit block). The rules-read advisory rides the two `bkit-preflight.sh` hooks at session start and the `bkit-rules` hook at the first tool call. See `.bkit/providers.md` § Hooks. A consumer file with no markers gets the block appended. Wire its exported function into your driver.
|
|
282
282
|
|
|
283
283
|
### What install writes
|
|
284
284
|
|
|
@@ -291,7 +291,7 @@ Block updates keep the comment prefixes (`# `, `// `) before the markers.
|
|
|
291
291
|
| `.gitignore` | core | `.bkit/shared/gitignore` | Tier 2 html-comment |
|
|
292
292
|
| `AGENTS.md` | core | `.bkit/core/AGENTS.md` | Tier 2 html-comment |
|
|
293
293
|
| `CLAUDE.md` | claude | `.bkit/shared/CLAUDE.md` | Tier 2 html-comment |
|
|
294
|
-
| `docs
|
|
294
|
+
| `docs/{architecture,technology,security,data-schema,testing,deployments,observability,design,noise,setup}.md` | project | starters in `.bkit/templates/docs/` | Never written by install or upgrade. Copy a starter into `docs/` and add its row to `Project Documents` in `.agents/docs.md`; install and upgrade register present documents, and remove the ownership wrapper from a copy an older release installed. |
|
|
295
295
|
| `docs/templates/bkit-*.md` | core | `.bkit/core/docs/templates/` | Tier 2 html-comment |
|
|
296
296
|
| `.gitattributes` | core | `.bkit/shared/.gitattributes` | Tier 2 html-comment (`merge=union` for the append-only ledgers) |
|
|
297
297
|
| `.bkit/templates/**` | — | the whole `.bkit/templates/` root | Raw copies, refreshed on every install and upgrade; never hashed. Upgrade prints the changed paths. |
|
|
@@ -303,6 +303,7 @@ Block updates keep the comment prefixes (`# `, `// `) before the markers.
|
|
|
303
303
|
| `.claude/hooks/bkit-preflight.sh` | claude | `.bkit/core/.claude/hooks/` | Tier 2 html-comment (`# ` prefix) |
|
|
304
304
|
| `.claude/hooks/bkit-gateguard.cjs` | claude | `.bkit/core/.claude/hooks/` | Tier 2 slash-comment |
|
|
305
305
|
| `.claude/hooks/bkit-readguard.cjs` | claude | `.bkit/core/.claude/hooks/` | Tier 2 slash-comment. Repeat-read advisory. |
|
|
306
|
+
| `.claude/hooks/bkit-guardrails.cjs` | claude | `.bkit/core/.claude/hooks/` | Tier 2 slash-comment. Refuses the shell deny tier; advises on curl / wget hosts and shell edits. |
|
|
306
307
|
| `.mcp.json` | claude | `.bkit/shared/.mcp.json` | Shared JSON: bkit owns `mcpServers.<tracker>` only; absent file → the tracker-filtered render |
|
|
307
308
|
| `.bkit/.env.example` | claude | `.bkit/shared/.bkit/.env.example` | Tier 1 (fully managed). Real values go in `.bkit/.env`. |
|
|
308
309
|
| `.cursor/commands/bkit-*.md` | cursor | `.bkit/core/workflows/` (T1+T2 transforms) | Host pass — always overwrite |
|
|
@@ -322,6 +323,7 @@ Block updates keep the comment prefixes (`# `, `// `) before the markers.
|
|
|
322
323
|
| `.opencode/commands/bkit-*.md` | OpenCode | `.bkit/core/workflows/` | Host pass — always overwrite |
|
|
323
324
|
| `.opencode/agents/bkit-*.md` | OpenCode | `.bkit/core/prompts/` | Host pass — always overwrite |
|
|
324
325
|
| `.opencode/plugin/bkit-gateguard.js` | OpenCode | `.bkit/core/.opencode/plugin/` | Tier 2 slash-comment |
|
|
326
|
+
| `.opencode/plugin/bkit-guardrails.js` | OpenCode | `.bkit/core/.opencode/plugin/` | Tier 2 slash-comment. Refuses the shell deny tier. |
|
|
325
327
|
| `.opencode/plugin/bkit-readguard.js` | OpenCode | `.bkit/core/.opencode/plugin/` | Tier 2 slash-comment. Repeat-read advisory. |
|
|
326
328
|
| `.claude/hooks/bkit-cloud-bootstrap.sh` | — | `.bkit/templates/.claude/hooks/` | Copy-and-own template: no module writes it; adopt it from `.bkit/templates/` (the SessionStart entry runs it only when present). |
|
|
327
329
|
|
|
@@ -329,7 +331,7 @@ The cloud workflow and the Cursor Background Agent files are templates the `--au
|
|
|
329
331
|
|
|
330
332
|
### Optional post-install decisions (tracker + cloud agents)
|
|
331
333
|
|
|
332
|
-
Two capabilities are opt-in and left out of the default install: the **issue tracker** (`--tracker=github|linear|jira`) and **cloud agents** (`--auto=claude|cursor
|
|
334
|
+
Two capabilities are opt-in and left out of the default install: the **issue tracker** (`--tracker=github|linear|jira`) and **cloud agents** (`--auto=claude|opencode|codex|cursor`). The default install ships zero cloud footprint. While a choice is undecided, its advisory fires (`tracker-setup-none` / `cloud-router-none`). Setting `"none"` in `bkit.tracker.default` / `bkit.cloud.agent` silences it. The dependency updater, security scan and test lint are copy-and-own templates. The choices, the defaults and how to decide are in `.bkit/install.md` § Optional post-install decisions. The template catalog is in `.bkit/templates.md`.
|
|
333
335
|
|
|
334
336
|
### Updater PRs against your workflows
|
|
335
337
|
|
|
@@ -339,7 +341,7 @@ Two capabilities are opt-in and left out of the default install: the **issue tra
|
|
|
339
341
|
|
|
340
342
|
## Triggering workflows
|
|
341
343
|
|
|
342
|
-
|
|
344
|
+
Three paths exist: a Linear comment (cloud), Claude (interactive, local) and Cursor (interactive, local). All three run the same workflow from `.bkit/core/workflows/`. The compute source and the orchestrator model differ.
|
|
343
345
|
|
|
344
346
|
### From a tracker comment (cloud — Cursor Cloud Agent)
|
|
345
347
|
|
|
@@ -355,7 +357,7 @@ There are three paths: a Linear comment (cloud), Claude (interactive, local) and
|
|
|
355
357
|
|
|
356
358
|
**GitHub tracker:** a PR label triggers the run, through the Cursor Automations trigger "Pull request label changed". `bkit:auto` on the PR (from `bkit-build`) triggers dispatch, and the phase label (`bkit:plan`, `bkit:build`, etc.) selects the workflow. Issue comments go through the GitHub MCP. `/bkit-design` / `/bkit-plan` have no PR, so with the GitHub tracker they are local-IDE-only on Cursor cloud.
|
|
357
359
|
|
|
358
|
-
**Requirements (Linear):** the `
|
|
360
|
+
**Requirements (Linear):** the `bkit:auto` label and a state that is not finished (judged by state category). `BKIT_LINEAR_API_KEY`, `BKIT_CURSOR_API_KEY`, `BKIT_ANTHROPIC_API_KEY` and `BKIT_GH_TOKEN` in the Cursor Cloud Agent dashboard.
|
|
359
361
|
|
|
360
362
|
**Requirements (GitHub):** `BKIT_GH_TOKEN`, `BKIT_CURSOR_API_KEY` and `BKIT_ANTHROPIC_API_KEY` in the dashboard. The Cursor GitHub App on the repo/org. `GITHUB_ISSUE_ID` comes from the PR body's `<!-- bkit:issue=#NNN -->`, with no manual setup.
|
|
361
363
|
|
|
@@ -378,7 +380,7 @@ Claude reads the issue, its comments and the plan files through the tracker MCP.
|
|
|
378
380
|
|
|
379
381
|
**Manual batch of held builds:** merge the held `feat/{FID}` branches into one branch off `dev` yourself, push it and open one PR. You own the push, the PR, the CI gate, the sweep and the docs sync. One head commit means post-merge auto-debug sees only the last FID. Never batch migrations.
|
|
380
382
|
|
|
381
|
-
**Requirements:** `BKIT_GH_TOKEN` and an active Claude session (subscription or `BKIT_ANTHROPIC_API_KEY`). `BKIT_LINEAR_API_KEY` as well when `bkit.tracker.default = "linear"`, and `BKIT_JIRA_API_KEY` when it is `"jira"`. The session model is the orchestrator pin in `.bkit/prompts.md` § Orchestrators (`Claude` column). Set it with `/model` before you invoke a command. This file does not repeat the pin.
|
|
383
|
+
**Requirements:** `BKIT_GH_TOKEN` and an active Claude session (subscription or `BKIT_ANTHROPIC_API_KEY`). `BKIT_LINEAR_API_KEY` as well when `bkit.tracker.default = "linear"`, and `BKIT_JIRA_API_KEY` when it is `"jira"`. A session that carries an issue id (`GITHUB_ISSUE_ID`) is guarded: it stops when the issue lost `bkit:auto` or is finished, on GitHub, Linear and Jira. A session with no issue id is unguarded. The session model is the orchestrator pin in `.bkit/prompts.md` § Orchestrators (`Claude` column). Set it with `/model` before you invoke a command. This file does not repeat the pin.
|
|
382
384
|
|
|
383
385
|
### From Cursor (interactive — local)
|
|
384
386
|
|