@cbartens/bkit 6.1.1 → 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 +42 -32
- 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 +97 -36
- package/.bkit/core/.bkit/templates.md +162 -34
- 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 +89 -37
- package/.bkit/core/engine/checks/after/index.ts +15 -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 +64 -11
- package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
- 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 +148 -14
- 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 +3 -1
- 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/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-machine-lock.sh +511 -103
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +228 -35
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +270 -2
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +92 -63
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
- package/.bkit/templates/slop-scan.config.json +2 -0
- package/CHANGELOG.md +64 -0
- package/DETAILS.md +24 -19
- package/README.md +1 -1
- package/dist/checks/after/auth.js +114 -46
- package/dist/checks/after/github.js +77 -35
- package/dist/checks/after/index.js +12 -3
- 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 +56 -12
- package/dist/commands/ci/push-gate.js +79 -44
- 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 +133 -14
- 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 +3 -1
- 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 +22 -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
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
|
|
14
14
|
## What each template is for
|
|
15
15
|
|
|
16
|
-
The adoption order is the `bkit tips` order. The machine lock has no tip, so adopt it when test gates or local services need to run one at a time across checkouts. The health check has no tip either: the `bkit-stub-health` advisory raises it while your CI copy keeps that stub. The sections below give each template's install steps and traps.
|
|
16
|
+
The adoption order of the tool templates is the `bkit tips` order; for the project docs it is § Project docs — adoption order. The machine lock has no tip, so adopt it when test gates or local services need to run one at a time across checkouts. The health check has no tip either: the `bkit-stub-health` advisory raises it while your CI copy keeps that stub. The sections below give each template's install steps and traps.
|
|
17
17
|
|
|
18
18
|
<!-- prettier-ignore -->
|
|
19
19
|
| Template | What it's for | Skip it and |
|
|
@@ -33,12 +33,13 @@ The adoption order is the `bkit tips` order. The machine lock has no tip, so ado
|
|
|
33
33
|
| Secrets sync | One local file → every secret store; proves copies match without printing values. | Hand-copied secrets drift: "works for me, broken in production". |
|
|
34
34
|
| Issue forms | Three forms (idea, well-defined change, bug) asking for what design, plan / build and debug read first. | Issues arrive as a title and a line; agents guess at scope, "done" and repro steps. |
|
|
35
35
|
| graphify | Code map (`docs/capabilities.md`) agents check before building something again. | Agents rediscover structure each run; ripple effects missed. |
|
|
36
|
+
| Component map | Purpose-based overview of the repository's responsibilities and main journeys. | Readers have to infer what the system does from implementation details. |
|
|
36
37
|
| Dependabot / Renovate | Small grouped update PRs; pinned Actions; security fixes skip the queue. | Updates pile into one large risky upgrade. |
|
|
37
38
|
| Trivy | Fails CI on a known-vulnerable package in any language, a risky container or cluster setting, or a committed secret; a daily run catches advisories with no fix yet. | A vulnerable package or leaked key merges unnoticed; an advisory with no fixed release never shows up anywhere. |
|
|
38
39
|
| Prettier tables | One edited cell = one changed row in the diff. | A one-word table edit diffs as the whole table. |
|
|
39
40
|
| tmp/ prune | Each push deletes scratch files agents left in `tmp/` untouched for a week. | `tmp/` keeps growing; old logs and scratch files are never cleared. |
|
|
40
41
|
| Disk prune | Your own cleanup steps (build caches, Docker, simulators) run on commit, on push, and before a worktree is made on a low disk. bkit deletes nothing itself. | Caches fill the disk until no worktree can be made; every workflow stops. |
|
|
41
|
-
| Machine lock | Named locks run one gate at a time across repositories; the unnamed lock protects local services every worktree shares. A second run waits and names the holder. | Test gates compete for CPU,
|
|
42
|
+
| Machine lock | Named locks run one gate at a time across repositories; the unnamed lock protects local services every worktree shares. A second run waits and names the holder, and `run` stops a command that holds the tests lock past the hold limit. | Test gates compete for CPU, a reset stops the stack under another worktree's test run, or a hung gate holds the lock and every push waits. |
|
|
42
43
|
| Cursor editor + cloud agent | Format-on-save, recommended extensions, Cursor cloud-agent image. | Cursor edits miss project formatting; no Cursor cloud agent. |
|
|
43
44
|
| Launchd GUI env | macOS apps opened from the Dock get the same tokens as the terminal. | Dock-launched editors start signed out. |
|
|
44
45
|
|
|
@@ -52,8 +53,8 @@ The adoption order is the `bkit tips` order. The machine lock has no tip, so ado
|
|
|
52
53
|
| Health check | `.bkit/templates/.github/workflows/bkit-health.yml` | `.github/workflows/bkit-health.yml` | that file |
|
|
53
54
|
| Cloud-agent workflow | `.bkit/templates/.github/workflows/bkit-cloud.yml` | `.github/workflows/bkit-cloud.yml` | that file |
|
|
54
55
|
| Git hooks (Husky) | `.bkit/templates/.husky/pre-commit`, `.bkit/templates/.husky/pre-push` | `.husky/pre-commit`, `.husky/pre-push` | both files |
|
|
55
|
-
| Prettier ignore list | `.bkit/templates
|
|
56
|
-
| lint-staged | `.bkit/templates
|
|
56
|
+
| Prettier ignore list | `.bkit/templates/prettierignore.example` | `.prettierignore` | that file |
|
|
57
|
+
| lint-staged | `.bkit/templates/lintstagedrc.example.json` | `.lintstagedrc.json` | that file |
|
|
57
58
|
| Vale | `.bkit/templates/.vale.ini`, `.bkit/templates/.vale/styles/Bkit/` | `.vale.ini`, `.vale/styles/Bkit/` | `.vale.ini` + the four Bkit styles |
|
|
58
59
|
| slop-scan | `.bkit/templates/slop-scan.config.json`, `.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs` | `slop-scan.config.json`, `scripts/slop/bkit-slop-type-suppression.mjs` | both files |
|
|
59
60
|
| Oxlint | `.bkit/templates/.oxlintrc.json` | `.oxlintrc.json` | that file |
|
|
@@ -67,14 +68,15 @@ The adoption order is the `bkit tips` order. The machine lock has no tip, so ado
|
|
|
67
68
|
| Serena | `.bkit/templates/scripts/serena/`, `.bkit/templates/.serena/project.yml` | `scripts/serena/`, `.serena/project.yml`, merge `bkit-serena.mcp.json` into `.mcp.json` | `project.yml` only |
|
|
68
69
|
| Issue forms | `.bkit/templates/.github/ISSUE_TEMPLATE/` | `.github/ISSUE_TEMPLATE/` | the forms you use |
|
|
69
70
|
| graphify | `.bkit/templates/scripts/graphify/`, `.bkit/templates/.graphifyignore`, `.bkit/templates/docs/capabilities.md` | same paths at the repo root | `docs/capabilities.md` |
|
|
71
|
+
| Component map | `.bkit/templates/docs/components.md` | `docs/components.md` | the populated document |
|
|
70
72
|
| Secrets sync | `.bkit/templates/scripts/secrets/` | `scripts/secrets/` | both files; never `bkit-secrets-state.json` |
|
|
71
73
|
| Prettier tables | `.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs` | `scripts/prettier/` | that file |
|
|
72
74
|
| tmp/ prune | `.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs` | `scripts/cleanup/` | that file |
|
|
73
75
|
| Disk prune | `.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs`, `bkit-disk-prune.machine.mjs` | `scripts/cleanup/bkit-disk-prune.mjs`, `~/.config/bkit/disk-prune.mjs` | `scripts/cleanup/bkit-disk-prune.mjs` only |
|
|
74
|
-
| Machine lock | `.bkit/templates/scripts/ci/bkit-machine-lock.sh` | `scripts/ci/` |
|
|
76
|
+
| Machine lock | `.bkit/templates/scripts/ci/bkit-machine-lock.sh`, `bkit-test-awake.mjs` | `scripts/ci/` | both files |
|
|
75
77
|
| Local test sleep prevention | `.bkit/templates/scripts/ci/bkit-test-awake.mjs`, `bkit-test-awake.test.mjs` | `scripts/ci/` | both files |
|
|
76
78
|
| Context-fetch blocks | `.bkit/templates/context/bkit-<provider>.md` | below `<!-- bkit:end -->` in `.agents/context.md` | the blocks you use |
|
|
77
|
-
| Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file |
|
|
79
|
+
| Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file; it compares `BKIT_CLOUD_ALLOWLIST_FINGERPRINT` with `.bkit/allowlist.json` and warns on a mismatch, and `bkit check` raises `cloud-bootstrap-fingerprint-missing` for a copy that never reads the variable |
|
|
78
80
|
|
|
79
81
|
Placeholders: the copies keep them raw, so replace each one in your copy:
|
|
80
82
|
|
|
@@ -83,14 +85,14 @@ Placeholders: the copies keep them raw, so replace each one in your copy:
|
|
|
83
85
|
| --- | --- | --- | --- |
|
|
84
86
|
| `{{DEFAULT_BRANCH}}` | `bkit-ci.yml` (`on.push` / `on.pull_request` branches; stub comments), `bkit-trivy.yml` (`on.push` / `on.pull_request` branches), `bkit-health.yml` (`on.workflow_run` branches) | your production branch | `origin/HEAD` unless it is `dev`, else `main` |
|
|
85
87
|
| `{{PRODUCTION_URL}}` | `bkit-health.yml` (`env.PRODUCTION_URL`) | the origin production serves | `https://example.com` |
|
|
86
|
-
| `{{NODE_VERSION}}` | `bkit-ci.yml` (`actions/setup-node` `node-version`, both lanes) | your Node major, or swap the line for `node-version-file: .nvmrc` | `.nvmrc`, then `engines.node`, then `22` |
|
|
88
|
+
| `{{NODE_VERSION}}` | `bkit-ci.yml` (`actions/setup-node` `node-version`, both lanes), `bkit-cloud.yml` (`actions/setup-node` `node-version`, the context job's bkit install) | your Node major, or swap the line for `node-version-file: .nvmrc` | `.nvmrc`, then `engines.node`, then `22` |
|
|
87
89
|
| `{{CLOUD_RUNNER}}` | `bkit-cloud.yml` (`runs-on`, all three jobs) | a runner label | `ubuntu-latest` |
|
|
88
90
|
| `{{SCRIPT_PATH}}` | `bkit-launchd.plist` (`ProgramArguments`) | absolute path to the loader script, outside a TCC-protected folder (see § Launchd GUI environment) | `/Users/<you>/.config/bkit/bkit-launchd-env.sh` |
|
|
89
91
|
| `{{ENV_FILE}}` | `bkit-launchd.plist` (`ProgramArguments`, `WatchPaths`) | absolute path to your env file | `/Users/<you>/.config/bkit/launchd.env` |
|
|
90
92
|
|
|
91
93
|
- `bkit install` / `bkit upgrade` refresh `.bkit/templates/` to the package's templates, unsubstituted. `bkit check` fails on a stale copy. `bkit uninstall` removes the folder, never an adopted copy.
|
|
92
94
|
- **What changed on upgrade.** `bkit upgrade` lists the changed, added and removed template paths. For each one you adopted, run `diff .bkit/templates/<path> <path>`, and merge what you want. The placeholder lines differ by design. `git diff .bkit/templates` in the upgrade commit shows the package change.
|
|
93
|
-
- Repo gates that scan the whole repo (prettier, Vale, slop-scan, eslint, tsc) must ignore `.bkit/templates/`. The
|
|
95
|
+
- Repo gates that scan the whole repo (prettier, Vale, slop-scan, eslint, tsc) must ignore `.bkit/templates/`. The `prettierignore.example`, `.vale.ini`, `slop-scan.config.json` and `.oxlintrc.json` templates already do. Check that your adopted copy does too.
|
|
94
96
|
- Templates are written in Node unless the tool they wrap already needs another runtime (graphify and Serena: Python and shell launchers; git hooks: POSIX `sh`; local stack lock: bash and perl, because shell runners source it).
|
|
95
97
|
- `bkit.dependencies.updater` names the adopted updater (`"renovate"` / `"dependabot"`). Install fills it from the config present. `"none"` skips the install-time absence advisory. `bkit check` blocks when the setting and the configs disagree.
|
|
96
98
|
- No template has a manifest key. `docs/templates/bkit-audit-adoption.md` lists every template on each run, as adopted and wired, or as not adopted with the reason.
|
|
@@ -194,6 +196,8 @@ pnpm add -D prettier@^3.5.3 slop-scan@^0.3.0 lint-staged@^17.0.0 husky@^9.1.7
|
|
|
194
196
|
- **If** the stack is not Node → point each gate at your own commands, and keep the gate names.
|
|
195
197
|
- `bkit:test:file` runs one test file and writes a JUnit report to `$BKIT_TEST_REPORT`. bkit appends the file's repo-relative path. `/bkit-build` reads the report for test-first. It is not seeded, and `test-file-script-missing` fires until it is declared.
|
|
196
198
|
- Vitest: `"bkit:test:file": "vitest run --reporter=default --reporter=junit --outputFile.junit=\"$BKIT_TEST_REPORT\""`.
|
|
199
|
+
- jest: `jest --runTestsByPath` with the `jest-junit` reporter and `JEST_JUNIT_OUTPUT_FILE="$BKIT_TEST_REPORT"`.
|
|
200
|
+
- **If** jest gets the path without `--runTestsByPath` → it reads the path as a regex, so a folder such as `(tabs)` matches no file and no report is written.
|
|
197
201
|
- Call the runner directly, not through a caching task runner.
|
|
198
202
|
- `bkit:lint:file` lints one test file with the static gate's rules, and exits 0 when clean. bkit appends the path. `bkit tests red` runs it on each planned test file before running the file, and records a `lint` gap for the file's tests while it fails. It is not seeded, and `lint-file-script-missing` fires once `bkit:test:file` is declared without it.
|
|
199
203
|
- ESLint: `"bkit:lint:file": "eslint --max-warnings=0"`.
|
|
@@ -203,7 +207,7 @@ pnpm add -D prettier@^3.5.3 slop-scan@^0.3.0 lint-staged@^17.0.0 husky@^9.1.7
|
|
|
203
207
|
|
|
204
208
|
## Local test sleep prevention
|
|
205
209
|
|
|
206
|
-
Copy `.bkit/templates/scripts/ci/bkit-test-awake.mjs` and its adjacent test into `scripts/ci/`. Install its command-launching dependency with `pnpm add -D cross-spawn@7.0.6`; it handles Windows package-command shims and argument escaping. Prefix each local test script, including individual-file runners, with `node scripts/ci/bkit-test-awake.mjs`. Wrap a complete command chain with `--shell` and one double-quoted command string. Leave CI calling the same scripts.
|
|
210
|
+
Copy `.bkit/templates/scripts/ci/bkit-test-awake.mjs` and its adjacent test into `scripts/ci/`. Install its command-launching dependency with `pnpm add -D cross-spawn@7.0.6`; it handles Windows package-command shims and argument escaping, and the wrapper loads it only on Windows. Prefix each local test script, including individual-file runners, with `node scripts/ci/bkit-test-awake.mjs`. Wrap a complete command chain with `--shell` and one double-quoted command string. Leave CI calling the same scripts.
|
|
207
211
|
|
|
208
212
|
```json
|
|
209
213
|
{
|
|
@@ -215,7 +219,7 @@ Copy `.bkit/templates/scripts/ci/bkit-test-awake.mjs` and its adjacent test into
|
|
|
215
219
|
|
|
216
220
|
Keep each script's existing runner flags and report settings when adding the prefix. Run the wrapper's tests with `node --test scripts/ci/bkit-test-awake.test.mjs`. For a direct runner invocation, use `node scripts/ci/bkit-test-awake.mjs pnpm exec vitest run path/to/example.test.ts`.
|
|
217
221
|
|
|
218
|
-
On macOS, the wrapper holds `caffeinate -is -w` against its own process and releases it when the command exits. It forwards cancellation to the command and retains the caller's process group so external hard timeouts still reach the tests. POSIX `--shell` chains stop after cancellation and wait for descendant cleanup. Signals reach command owners first; surviving orphan roots receive cancellation after their owner exits. Live owners retain responsibility for their descendants and machine-lock lifetime. A command that starts cleanup children during cancellation must wait for them before exiting. If process inspection is unavailable, the wrapper reports that limitation and waits for foreground completion or a successful cleanup inspection. Linux and Windows do not require `caffeinate`. Test timeouts are unchanged. Keep the lid open;
|
|
222
|
+
On macOS, the wrapper holds `caffeinate -is -w` against its own process and releases it when the command exits. It forwards cancellation to the command and retains the caller's process group so external hard timeouts still reach the tests. POSIX `--shell` chains stop after cancellation and wait for descendant cleanup. Signals reach command owners first; surviving orphan roots receive cancellation after their owner exits. Live owners retain responsibility for their descendants and machine-lock lifetime. A command that starts cleanup children during cancellation must wait for them before exiting. If process inspection is unavailable, the wrapper reports that limitation and waits for foreground completion or a successful cleanup inspection. Linux and Windows do not require `caffeinate`. Test timeouts are unchanged. A Ctrl-C at the terminal already reaches the command, so the wrapper does not send INT again, but a `--shell` chain still waits for descendant cleanup. `--hold-s <N> [--grace-s <G>] [--stopped-file <P>] [--pass-fds <A,B>] --` before the command is the machine lock's hold limit (§ Machine lock): after N seconds the wrapper stops the command and every process under it and exits 124. `--stopped-file` names a file the wrapper creates as that stop starts, so a caller can tell it from the command's own 124. `--pass-fds` hands the command the listed open descriptors above 2, which it otherwise does not receive. Leave it to the lock script; a test script does not pass it. Keep the lid open; `.bkit/workflows.md` § Test and release mechanics describes the limits.
|
|
219
223
|
|
|
220
224
|
`bkit tests` already protects the commands it launches using the packaged wrapper. Adopt this template for direct scripts and hooks. Existing consumer-owned scripts are not rewritten on upgrade.
|
|
221
225
|
|
|
@@ -269,13 +273,16 @@ A post-CI router that runs bkit workflows:
|
|
|
269
273
|
- Failed `dev` CI → `/bkit-debug {FID}`.
|
|
270
274
|
- `workflow_dispatch` runs any phase.
|
|
271
275
|
|
|
272
|
-
A `context` job resolves the phase and argument once. Then
|
|
276
|
+
A `context` job resolves the phase and argument once. Then three runner jobs follow, and only the one `bkit.cloud.agent` names starts, when its secret is set: `claude` (`claude-code-action`, https://github.com/anthropics/claude-code-action), `opencode` (`opencode run`, https://opencode.ai/docs/github/) and `codex` (`openai/codex-action`, https://github.com/openai/codex-action). `bkit install --auto=claude|opencode|codex` points at this file. The full recipe is in `.bkit/cloud.md` § Post-CI auto-routing.
|
|
273
277
|
|
|
274
|
-
- Install: `bkit install --auto=claude` (points at the `.claude/hooks/bkit-cloud-bootstrap.sh` template)
|
|
275
|
-
- Secrets for `claude`: `
|
|
276
|
-
- Secrets for `opencode`: `
|
|
278
|
+
- Install: `bkit install --auto=claude` (points at the `.claude/hooks/bkit-cloud-bootstrap.sh` template), `--auto=opencode` (needs `--opencode=<provider>` first) or `--auto=codex` (needs `--codex`). Each works with any wired tracker (GitHub, Linear or Jira).
|
|
279
|
+
- Secrets for `claude`: `BKIT_ANTHROPIC_API_KEY`, or keyless with the `ANTHROPIC_FEDERATION_RULE_ID` and `ANTHROPIC_ORGANIZATION_ID` repo variables, plus the Claude GitHub App (`/install-github-app`).
|
|
280
|
+
- Secrets for `opencode`: the installed provider's key, one of `BKIT_OPENCODE_API_KEY`, `BKIT_OPENROUTER_API_KEY`, `BKIT_OLLAMA_API_KEY`.
|
|
281
|
+
- Secrets for `codex`: `BKIT_OPENAI_API_KEY`.
|
|
282
|
+
- Tracker secrets: `BKIT_LINEAR_API_KEY` under Linear, `BKIT_JIRA_API_KEY` under Jira. The workflow reads them at step scope.
|
|
277
283
|
- Repo Actions permissions: read and write, with PR creation allowed.
|
|
278
|
-
- Adapt: `{{CLOUD_RUNNER}}` in all
|
|
284
|
+
- Adapt: `{{CLOUD_RUNNER}}` in all four jobs.
|
|
285
|
+
- The `codex` job runs `drop-sudo` on the runner (irreversible), so use an ephemeral runner.
|
|
279
286
|
- Traps:
|
|
280
287
|
- The file runs bkit by command name, so a changed invocation reaches you only as a changed template path on `bkit upgrade`. Diff it on every upgrade.
|
|
281
288
|
- The OpenCode install version is a plain argument. The `# renovate:` comment above it lets the example `renovate.json5` bump it.
|
|
@@ -285,7 +292,7 @@ A `context` job resolves the phase and argument once. Then two runner jobs follo
|
|
|
285
292
|
|
|
286
293
|
`pre-commit` runs `bkit:gate:format`. `pre-push` runs `bkit check` first, so a drifted install fails in seconds. Then it runs `bkit:gate:static-unit-integration` when package.json declares it, else `bkit:gate:static-unit` (`bkit:gate:static` on revert branches / commits; `bkit:gate:min` on a min push). It also runs the CI-suppressing-token guards, the dependency audit (§ Dependency audit) and the `tmp/` prune (§ tmp/ prune). Each hook ends by starting the disk prune (§ Disk prune).
|
|
287
294
|
|
|
288
|
-
Pre-push re-runs itself once with all its output copied to `tmp/pre-push.log`, which is rewritten on each push. It prints that path first and last, with the exit code. `--no-verify` and a checkout without husky (a linked worktree) write no log.
|
|
295
|
+
Pre-push re-runs itself once with all its output copied to `tmp/pre-push.log`, which is rewritten on each push. It prints that path first and last, with the exit code. `--no-verify` and a checkout without husky (a linked worktree) write no log. When the repo has an `.envrc`, `direnv` is on `PATH` and `CI` is unset, the inner run goes through `direnv exec .`, so the gate loads `.envrc` itself. On every path, with or without direnv, the gate unsets the bkit tooling keys (`BKIT_GH_TOKEN`, `BKIT_LINEAR_API_KEY`, `BKIT_JIRA_API_KEY`, `BKIT_ANTHROPIC_API_KEY`, `BKIT_CURSOR_API_KEY`, `BKIT_OPENCODE_API_KEY`, `BKIT_OPENROUTER_API_KEY`, `BKIT_OLLAMA_API_KEY`, `BKIT_OPENAI_API_KEY`) however they were loaded, plus every key `.bkit/.env` names. An `.envrc` that direnv cannot load blocks in seconds, before `bkit check`, and prints direnv's own output; only when direnv reports the file untrusted does it add the `direnv allow .` fix. A repo whose hook copy lacks this gets the `pre-push-direnv` tip.
|
|
289
296
|
|
|
290
297
|
Workflows care because they commit and push without `--no-verify`, so a failing hook stops a workflow. The throwaway `.worktrees/_land-{FID}` checkout runs its selected gate explicitly before pushing, with hooks disabled (§ One landing routine in `.bkit/workflows.md`). Reference: https://typicode.github.io/husky/.
|
|
291
298
|
|
|
@@ -298,13 +305,15 @@ chmod +x .husky/pre-commit .husky/pre-push
|
|
|
298
305
|
- Adapt: repo-only checks go below the bkit lines in each hook. What a gate runs belongs in the `bkit:gate:*` script, not the hook.
|
|
299
306
|
- Min push:
|
|
300
307
|
- **If** every file changed since each pushed commit left `origin/dev` (else `origin/main`) is one bkit writes or one `bkit.testing.minPushPaths` adds → `bkit:gate:min` replaces the full gate, and `MIN_PUSH=1`.
|
|
301
|
-
- The hook passes each remote-old and pushed-new commit as `bkit ci min-push --update=<old>:<new>`. A fast-forward bookkeeping increment also qualifies when a successful local full-gate receipt covers an ancestor of the old commit and every change since that checked commit is allowed.
|
|
302
|
-
- `bkit ci push-gate --gate=<script>` runs the selected consumer script. A successful deepest full push gate records its clean, unchanged commit and script definitions in the repository's Git metadata. A failed or interrupted full check prevents reuse of earlier evidence until a later full check succeeds. Minimum and revert gates create no full-gate evidence. Receipts are local; a new clone starts without them.
|
|
303
|
-
- What bkit writes = ship's `--scope=pr` allow-list (`.bkit/workflows.md` § `/bkit-ship` —
|
|
308
|
+
- The hook passes each remote-old and pushed-new commit as `bkit ci min-push --update=<old>:<new>`. A fast-forward bookkeeping increment also qualifies when a successful local full-gate receipt covers an ancestor of the old commit and every change since that checked commit is allowed. A new branch qualifies the same way: a receipt on an ancestor of the pushed commit, with only bookkeeping paths changed since it and no later failure, takes the minimum gate.
|
|
309
|
+
- `bkit ci push-gate --gate=<script>` runs the selected consumer script. A successful deepest full push gate records its clean, unchanged commit and script definitions in the repository's Git metadata. A failed or interrupted full check prevents reuse of earlier evidence until a later full check succeeds. A check still running blocks reuse too; one whose process has exited without finishing counts as failed, and the next full check on that commit clears it. A tests-lock wait that gives up (the lock script's exit 75, with `gave-up` in its status file) is not a check, so it leaves the evidence as it was. `bkit tests run` records the same receipt when it runs the deepest full gate (build Step 12) without `--changed-since`; there, uncommitted paths inside the min-push (bookkeeping) paths do not block it, since every engine call appends to `status.jsonl`, and any uncommitted code, a lock wait (exit 81) or a lighter gate records none. Minimum and revert gates create no full-gate evidence. Receipts are local; a new clone starts without them.
|
|
310
|
+
- What bkit writes = ship's `--scope=pr` allow-list (`.bkit/workflows.md` § `/bkit-ship` — 12 steps) plus `docs/plans/**` and `docs/audits/**`.
|
|
311
|
+
- A change to a top-level `docs/templates/bkit-audit-*.md` also counts as written by bkit when the file's text through its single `<!-- bkit:end -->` line is the same at both ends of the range, so only the `Project Instructions` section below it changed. A new, deleted or renamed template, a second marker line, or any change at or above the marker keeps the full gate. A template with CRLF line endings never qualifies, because a marker followed by `\r` is not line-anchored. Other templates, such as `docs/templates/bkit-plan.md`, keep the full gate. "What bkit writes" in the `bkit ci min-push` summary covers the audit reports and the audit templates' project sections.
|
|
304
312
|
- The setting takes `package.json` globs: `*` matches one folder and `**` any depth. The default is `[]`, which leaves what bkit writes alone, because the setting only adds to it.
|
|
305
313
|
- `bkit ci min-push` decides from files, never from `[skip ci]`, because that is a typed label and GitHub reads the last commit only.
|
|
306
|
-
- Empty trigger commits need checked-ancestor evidence. Missing evidence, unreadable ranges, rewritten history, or any outgoing ref carrying new code keeps the full gate. A new branch
|
|
314
|
+
- Empty trigger commits need checked-ancestor evidence. Missing evidence, unreadable ranges, rewritten history, or any outgoing ref carrying new code keeps the full gate. A new branch qualifies from a receipted ancestor plus bookkeeping-only commits, or from its complete bookkeeping-only branch diff; a new branch with code after the receipted ancestor keeps the full gate.
|
|
307
315
|
- Min-push paths: list only files that no code, build or test reads.
|
|
316
|
+
- The floor already covers `docs/plans/**` and `docs/audits/**`, so the setting lists neither.
|
|
308
317
|
- Never list `docs/**`, because a doc can be test input.
|
|
309
318
|
- **If** a test reads a ledger → put that test into `bkit:gate:min`.
|
|
310
319
|
- `[skip ci]` guards:
|
|
@@ -312,6 +321,13 @@ chmod +x .husky/pre-commit .husky/pre-push
|
|
|
312
321
|
- With a PR open, `bkit ci bookkeeping-push --from=<remote head>` lets the push through when every file changed since the head the remote holds is on ship's `--scope=pr` allow-list. Such a push adds nothing that CI has not tested at that head.
|
|
313
322
|
- A rewritten head or a code file still blocks.
|
|
314
323
|
- On `dev` / `main`, the skip-CI check uses the complete branch diff, independently of local gate receipts. Code cannot skip CI merely because its local gate passed.
|
|
324
|
+
- PR conflict check:
|
|
325
|
+
- A fast check, run before `bkit check` and the gate. One `gh pr list --head <branch> --state open` lookup (every branch but `dev` / `main`) gives the PR number and its base; the `[skip ci]` guard reads the number from it.
|
|
326
|
+
- **If** the branch has an open PR → the hook fetches the base from `origin`, then runs `git merge-tree --write-tree --name-only` on `origin/<base>` and the pushed commit. Conflicts → the push is blocked, naming the files and the fix. This holds for a min push too, because a conflicting PR never starts CI.
|
|
327
|
+
- **If** `gh` is missing or fails, the clone is shallow (fix: `git fetch --unshallow`), the base fetch fails, or `git merge-tree` fails for another reason → the hook warns that the check was skipped, and the push goes on. No open PR → no fetch and no message.
|
|
328
|
+
- The lookup keeps same-repo PRs plus a cross-repository PR whose head repository is the push target. A fork PR with the same head branch name that is not the push target is ignored. It asks for up to 1000 open PRs; if a full page comes back with no match, the conflict check warns and skips, and the `[skip ci]` guard blocks a `[skip ci]` head, because it cannot tell that no PR is open. The base is fetched with an explicit refspec, and the trial merge ignores the work tree's `.gitattributes`, as GitHub does, so a `merge=union` ledger conflict blocks.
|
|
329
|
+
- `BKIT_PR_CONFLICT_CHECK=false` skips the whole check with one stderr line. `/bkit-ship` sets it on every push, because the conflict is what Step 4 merges away and a `dev` that moves after Step 4 is left to the Step 10 merge gate's `--fresh-base`. `/bkit-debug` sets it on its feature-branch pushes, so fix commits always reach `origin`.
|
|
330
|
+
- A repo whose hook copy lacks this gets the `pre-push-pr-conflict` tip.
|
|
315
331
|
- Slop base:
|
|
316
332
|
- **If** the push is to `dev` **and** `scripts/ci/lanes/bkit-resolve-push-base.mjs` is copied → the hook runs it with `--local --branch=dev --head=<pushed sha>`, and exports `SLOP_BASE_REF` as CI's push base. That base is the head of the last green CI push run on `dev`, else `origin/dev`. The hook prints the base and its source.
|
|
317
333
|
- Pre-push and CI slop then share a base, so a finding that an earlier red push landed fails locally too.
|
|
@@ -332,7 +348,7 @@ chmod +x .husky/pre-commit .husky/pre-push
|
|
|
332
348
|
pnpm add -D prettier@^3.5.3
|
|
333
349
|
```
|
|
334
350
|
|
|
335
|
-
1. Copy `.prettierignore` before the first `prettier --write`. bkit writes `.claude/`, `.cursor/`, `.opencode/`, `.mcp.json`, `.bkit/.env.example` and `docs/roadmap.md` in its own layout, so prettier reformatting them fights the next `bkit install` (`bkit check` drift).
|
|
351
|
+
1. Copy `.bkit/templates/prettierignore.example` to `.prettierignore` before the first `prettier --write`. bkit writes `.claude/`, `.cursor/`, `.opencode/`, `.mcp.json`, `.bkit/.env.example` and `docs/roadmap.md` in its own layout, so prettier reformatting them fights the next `bkit install` (`bkit check` drift).
|
|
336
352
|
2. Add `format:check` (§ Gate tool scripts). Reference: https://prettier.io/docs/install.
|
|
337
353
|
|
|
338
354
|
- Keep the `.bkit/templates/` line.
|
|
@@ -340,6 +356,8 @@ pnpm add -D prettier@^3.5.3
|
|
|
340
356
|
|
|
341
357
|
## lint-staged — `.lintstagedrc.json`
|
|
342
358
|
|
|
359
|
+
Copy `.bkit/templates/lintstagedrc.example.json` to `.lintstagedrc.json`. The samples under `.bkit/templates/` carry non-dotfile names so prettier and lint-staged do not read them as live config; `bkit upgrade` removes the old dotfile-named samples (`.lintstagedrc.json`, `.prettierignore`) from `.bkit/templates/`. bkit writes no lint-staged config into your repo: when `bkit:gate:format` runs `lint-staged` without a `--config` path, lint-staged is a dependency and no config exists, install, check and upgrade print `no root lint-staged config — commits will fail. Fix: cp .bkit/templates/lintstagedrc.example.json .lintstagedrc.json` after their own log prefix (`[bkit-install]`, `[bkit-check]`, `[bkit-upgrade]`).
|
|
360
|
+
|
|
343
361
|
It runs prettier over staged files. `bkit:gate:format` (the pre-commit hook) calls it. Reference: https://github.com/lint-staged/lint-staged.
|
|
344
362
|
|
|
345
363
|
```bash
|
|
@@ -391,6 +409,8 @@ cp .bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs scripts/slop/
|
|
|
391
409
|
|
|
392
410
|
It fails `lint` on a test that cannot fail. Oxlint (a fast linter) runs five rules on test files only, with all other checks off. It fits JS / TS repos with Vitest or Jest. Reference: https://oxc.rs/docs/guide/usage/linter.html.
|
|
393
411
|
|
|
412
|
+
- The `.bkit/templates/.oxlintrc.json` sample keeps its dotfile name: oxlint run from a consumer root as `oxlint -c .oxlintrc.json` reports a violating test file at the root and reports nothing for the same file under `.bkit/templates/`, so the sample does not act as live config.
|
|
413
|
+
|
|
394
414
|
```bash
|
|
395
415
|
pnpm add -D oxlint@^1.87.0 oxlint-tsgolint@^7.0.2004
|
|
396
416
|
cp .bkit/templates/.oxlintrc.json .oxlintrc.json
|
|
@@ -433,6 +453,7 @@ direnv allow
|
|
|
433
453
|
```
|
|
434
454
|
|
|
435
455
|
- Adapt: add one `dotenv_if_exists <path>` line per extra env file.
|
|
456
|
+
- The pre-push hook loads `.envrc` itself on push (§ Git hooks — Husky), so an agent's shell that never loaded it still pushes with it. Run `direnv allow .` once per folder, or the push blocks.
|
|
436
457
|
- `unset` the keys that must stay out of the shell. They are dropped from the cloud env blocks too.
|
|
437
458
|
|
|
438
459
|
## Launchd GUI environment — tokens for Dock-launched apps
|
|
@@ -501,7 +522,7 @@ gh api -X PUT 'repos/{owner}/{repo}/vulnerability-alerts'
|
|
|
501
522
|
gh api -X PUT 'repos/{owner}/{repo}/automated-security-fixes'
|
|
502
523
|
```
|
|
503
524
|
|
|
504
|
-
Renovate (Mend): commit `.github/renovate.json5` on the default branch, then install the App at https://github.com/apps/renovate in the GitHub UI.
|
|
525
|
+
Renovate (Mend): commit `.github/renovate.json5` on the default branch, then install the App at https://github.com/apps/renovate in the GitHub UI. `gh` has no equivalent.
|
|
505
526
|
|
|
506
527
|
Renovate (self-hosted): also copy `bkit-renovate.yml`, then set its platform token. Use a fine-grained PAT for one owner, and a classic one across owners. The permissions are in `docs/deployments.md` § Dependency updaters.
|
|
507
528
|
|
|
@@ -513,13 +534,13 @@ gh secret set BKIT_GH_TOKEN
|
|
|
513
534
|
- The examples extend `config:best-practices`:
|
|
514
535
|
- Major bumps wait for a tick on the Dependency Dashboard (`dependencyDashboardApproval`).
|
|
515
536
|
- `lockFileMaintenance` runs monthly.
|
|
516
|
-
-
|
|
537
|
+
- Renovate never rebases an open PR by itself (`rebaseWhen: "never"`). A PR that conflicts waits until you tick its rebase checkbox.
|
|
517
538
|
- A `# renovate: datasource=<ds> depName=<name>` comment above a pinned CLI version (Dockerfile, `bkit-cloud.md`, workflows) lets the example `customManagers` entry bump it.
|
|
518
539
|
- For checksum-paired pins (Vale, gh, jq, Node, actionlint), update the sha256 by hand in the same PR. `Check Pinned Checksums` in `bkit-ci.yml` (`bkit ci pins`) fails the PR until the Dockerfile's hashes match.
|
|
519
540
|
- `bkit-renovate.yml` pins `renovate-version` to an exact release. The same kind of `# renovate:` comment keeps it current.
|
|
520
541
|
- `enabled: false` on a Renovate package rule does not stop digest pinning. Use `ignorePaths` to keep Renovate off a file.
|
|
521
542
|
- Land the config on the default branch before the bot runs. The examples set `baseBranchPatterns: ["dev"]`.
|
|
522
|
-
- The App install
|
|
543
|
+
- The App install and the self-hosted token are in `docs/deployments.md` § Dependency updaters. CVE handling is in `docs/deployments.md` § Manual CVE handling (when an alert fires).
|
|
523
544
|
|
|
524
545
|
## Dependency audit — known-vulnerable dependencies fail the push
|
|
525
546
|
|
|
@@ -623,7 +644,7 @@ The PyPI name is `serena-agent`, and the CLI is `serena`. PyPI `serena` is an un
|
|
|
623
644
|
|
|
624
645
|
## Issue forms — `.github/ISSUE_TEMPLATE/`
|
|
625
646
|
|
|
626
|
-
Issues are the first input every workflow reads.
|
|
647
|
+
Issues are the first input every workflow reads. Each way work starts has one form, and each form's intro names its next command. The section names, syntax and machine-read lines are in `.bkit/trackers.md` § Issue shapes. These forms serve the GitHub tracker alone, because Linear and Jira have their own templates. Reference: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms.
|
|
627
648
|
|
|
628
649
|
<!-- prettier-ignore -->
|
|
629
650
|
| Form | Use when | Next step | Asks for |
|
|
@@ -643,6 +664,84 @@ Issues are the first input every workflow reads. There is one form per way work
|
|
|
643
664
|
- Never add `bkit:*` labels, because workflows own them.
|
|
644
665
|
- **If** the repo has existing forms → copy only the `bkit-*` files you want. The names never collide.
|
|
645
666
|
|
|
667
|
+
## Project documents — starters and the index
|
|
668
|
+
|
|
669
|
+
Twelve project docs ship as starters in `.bkit/templates/docs/`: architecture, technology, security, data-schema, testing, deployments, observability, design, noise and setup, plus components (§ Component map — purpose and responsibilities) and capabilities (§ graphify — map). Copy a starter to `docs/{topic}.md` and add a matching row to `.agents/docs.md` `## Project Documents` in the same change; install and upgrade refresh only the starter, never your copy. A doc you keep under another name takes a row whose Scope says `Equivalent to docs/{topic}.md`, and install then adds no second row. A prompt that reads one of these docs applies it only when the doc is present and warns when it is not. Fill the starters in the order of § Project docs — adoption order.
|
|
670
|
+
|
|
671
|
+
## Project docs — adoption order
|
|
672
|
+
|
|
673
|
+
Fill the project docs in waves, because each doc reads facts the earlier ones record. Each starter's **Fill these first** line lists the docs in the **Fill these first** column below.
|
|
674
|
+
|
|
675
|
+
<!-- prettier-ignore -->
|
|
676
|
+
| Wave | Doc | Fill these first |
|
|
677
|
+
| --- | --- | --- |
|
|
678
|
+
| 1 | `docs/idea.md` | — |
|
|
679
|
+
| 2 | `docs/components.md` | `docs/idea.md` |
|
|
680
|
+
| 3 | `docs/technology.md` | `docs/components.md` |
|
|
681
|
+
| 3 | `docs/design.md` | `docs/components.md` |
|
|
682
|
+
| 4 | `docs/architecture.md` | `docs/technology.md` |
|
|
683
|
+
| 4 | `docs/setup.md` | `docs/technology.md` |
|
|
684
|
+
| 5 | `docs/security.md` | `docs/architecture.md` |
|
|
685
|
+
| 5 | `docs/testing.md` | `docs/architecture.md` |
|
|
686
|
+
| 5 | `docs/observability.md` | `docs/architecture.md` |
|
|
687
|
+
| 6 | `docs/data-schema.md` | `docs/security.md` |
|
|
688
|
+
| 6 | `docs/deployments.md` | `docs/testing.md`, `docs/observability.md` |
|
|
689
|
+
| 6 | `docs/noise.md` | `docs/observability.md` |
|
|
690
|
+
| 7 | `docs/capabilities.md` | `docs/deployments.md` |
|
|
691
|
+
|
|
692
|
+
A solid arrow means the first doc must exist before the second is started. A dotted arrow means the second doc starts without the first, but one section of it is finished or checked against the first, so come back to it once the first exists.
|
|
693
|
+
|
|
694
|
+
```mermaid
|
|
695
|
+
flowchart LR
|
|
696
|
+
IDEA["idea.md"] --> COMP["components"]
|
|
697
|
+
COMP --> TECH["technology"]
|
|
698
|
+
COMP --> DES["design"]
|
|
699
|
+
TECH -.-> DES
|
|
700
|
+
TECH --> ARCH["architecture"]
|
|
701
|
+
TECH --> SET["setup"]
|
|
702
|
+
ARCH -.-> SET
|
|
703
|
+
SEC -.-> SET
|
|
704
|
+
ARCH --> SEC["security"]
|
|
705
|
+
ARCH --> TEST["testing"]
|
|
706
|
+
ARCH --> OBS["observability"]
|
|
707
|
+
SEC -.-> OBS
|
|
708
|
+
SEC --> DATA["data-schema"]
|
|
709
|
+
DATA -.-> SEC
|
|
710
|
+
TEST --> DEP["deployments"]
|
|
711
|
+
OBS --> DEP
|
|
712
|
+
OBS --> NOISE["noise"]
|
|
713
|
+
DATA -.-> DEP
|
|
714
|
+
DATA -.-> TEST
|
|
715
|
+
DEP --> CAP["capabilities"]
|
|
716
|
+
```
|
|
717
|
+
|
|
718
|
+
The dotted arrows:
|
|
719
|
+
|
|
720
|
+
- **technology → design:** the colour and spacing variables table waits for technology to pick the styling tool. The rest of design does not.
|
|
721
|
+
- **architecture → setup:** the local services section (database, queues) is filled once architecture names them.
|
|
722
|
+
- **security → setup:** the environment variables table grows as security names secrets.
|
|
723
|
+
- **security → observability:** the log format section is checked against security's list of personal data, so none of it gets logged.
|
|
724
|
+
- **data-schema → testing:** the test data section (fixtures, seed, a fresh store per tier) is finished against the schema.
|
|
725
|
+
- **data-schema → deployments:** the migrations-at-deploy-time section waits for the schema.
|
|
726
|
+
- **data-schema → security:** the "Where stored" column of the PII table in `docs/security.md` is finished against `docs/data-schema.md`.
|
|
727
|
+
|
|
728
|
+
`docs/idea.md` is the owner's free-form notes. It has no template, is not indexed in `.agents/docs.md`, and stays after `docs/components.md` exists. The components starter reads these facts from it:
|
|
729
|
+
|
|
730
|
+
- Who the users are, the problem they have and the result they get.
|
|
731
|
+
- The platforms the app runs on.
|
|
732
|
+
- What the app does without a network connection.
|
|
733
|
+
- What must update live.
|
|
734
|
+
- The scale the app must handle.
|
|
735
|
+
- The hard external requirements, such as a law, a contract or a partner's interface.
|
|
736
|
+
|
|
737
|
+
**If** `docs/idea.md` is absent → the components starter takes the same facts from the README, an approved specification or the owner's answers.
|
|
738
|
+
|
|
739
|
+
## Component map — purpose and responsibilities
|
|
740
|
+
|
|
741
|
+
Follow the removable population guide in `.bkit/templates/docs/components.md` to create `docs/components.md`. It covers evidence gathering for existing and planned repositories, component selection, example rows, document registration and completion checks.
|
|
742
|
+
|
|
743
|
+
The project owns the populated document. Installation and upgrades refresh the template source without overwriting the adopted copy. Neither graphify nor Floorplan is required; the template's rules header defines the boundaries between the purpose-based overview and other documentation.
|
|
744
|
+
|
|
646
745
|
## graphify — map
|
|
647
746
|
|
|
648
747
|
graphify runs on demand only. It is not an installed skill or git hook. graphify ships an MCP server (`graphify-mcp`, stdio default). That server stays unwired, because its answers come from the `graph.json` snapshot, and build / debug agents invalidate the graph faster than it rebuilds. Serena, which has no index to go stale, owns the agent surface.
|
|
@@ -696,7 +795,7 @@ graphify-out/
|
|
|
696
795
|
- `.graphifyignore` merges `.gitignore`.
|
|
697
796
|
- Keep `package.json` in the corpus. Excluding it drops the workspace `name` fields that graphify resolves package imports with, and the graph still looks complete.
|
|
698
797
|
- Keep `tsconfig.json` out, because graphify reads `paths` regardless.
|
|
699
|
-
- Always run `scripts/graphify/bkit-graphify.sh`, which passes `--code-only` and `--no-label` and unsets API keys.
|
|
798
|
+
- Always run `scripts/graphify/bkit-graphify.sh`, which passes `--code-only` and `--no-label` and unsets API keys. No persistent LLM-off setting exists.
|
|
700
799
|
|
|
701
800
|
<!-- prettier-ignore -->
|
|
702
801
|
| Command | Does |
|
|
@@ -707,12 +806,15 @@ graphify-out/
|
|
|
707
806
|
| `pnpm bkit:graph:rollup` | Package and module views, plus `docs/capabilities.md` and its diagram copies. |
|
|
708
807
|
| `pnpm bkit:graph:check` | Rebuild and fail if `docs/capabilities.md` is not what this tree produces, or a diagram copy differs from it. Reads uncommitted edits. Shipped as a self-skipping CI step (every push and pull request; on a PR, GitHub's test merge into the base); enabled in bkit's own CI. |
|
|
709
808
|
| `bash scripts/graphify/bkit-graphify.sh check-at <rev>` | `check` in a throwaway checkout of `<rev>` (default HEAD); pre-push gate runs it on the commit pushed to dev. |
|
|
710
|
-
| `pnpm bkit:graph:refresh` | Rebuild register in a throwaway checkout of the staged files (the index) →
|
|
809
|
+
| `pnpm bkit:graph:refresh` | Rebuild register in a throwaway checkout of the staged files (the index) → replace the generated region of `docs/capabilities.md` → rewrite the diagram copies. Stage the change first, so a run before its commit builds the new state. Fixes a red gate; commit result. |
|
|
711
810
|
| `pnpm bkit:graph:scoped [path]` | One subtree. Default `apps/web/src`. |
|
|
712
811
|
| `pnpm bkit:graph:graphml` | Opt-in GraphML for Gephi / yEd. |
|
|
713
812
|
|
|
714
813
|
- `docs/graphify-out/` holds the raw `graph.json`, and `docs/graphify-out/reports/` holds the derived views.
|
|
715
|
-
- Copy `.bkit/templates/docs/capabilities.md` → `docs/capabilities.md` before the first rollup
|
|
814
|
+
- Copy `.bkit/templates/docs/capabilities.md` → `docs/capabilities.md` before the first rollup.
|
|
815
|
+
- `rollup`, `register` and `refresh` rewrite only the generated region of `docs/capabilities.md`: the text between its `<!-- graphify:start -->` line and its `<!-- graphify:end -->` line. The rest of the file is the project's.
|
|
816
|
+
- **If** the doc lacks exactly one marker pair in that order → the run stops and writes nothing.
|
|
817
|
+
- **If** the doc has no marker and its rules box says the whole file is generated → the run rebuilds it from the starter and keeps its Overrides block.
|
|
716
818
|
- To add a capability, add a rule in `bkit-graph-drift-rules.json`: lane, owner module, one literal marker. The shipped rules JSON has one example row. Replace it.
|
|
717
819
|
- The marker is a literal that only the owner should contain (a host, a header, a marker string). Never use the owner's exported function name, because every legitimate caller then reads as `bypassed`.
|
|
718
820
|
|
|
@@ -909,11 +1011,11 @@ cp .bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs ~/.config/bkit/di
|
|
|
909
1011
|
|
|
910
1012
|
## Machine lock
|
|
911
1013
|
|
|
912
|
-
The machine lock queues test gates across repositories and protects shared local services across worktrees. Copy the script and wire it into the commands that need the lock. An unwired repository takes no lock. The script requires Bash 3.2+ and `/usr/bin/perl`.
|
|
1014
|
+
The machine lock queues test gates across repositories and protects shared local services across worktrees. Copy the script and wire it into the commands that need the lock. An unwired repository takes no lock. The script requires Bash 3.2+ and `/usr/bin/perl`. A `run` that takes the `tests` lock also needs `node` on `PATH` and the current `bkit-test-awake.mjs` (one that takes `--hold-s`) beside the script, because that file enforces the hold limit; without them that `run` exits 73.
|
|
913
1015
|
|
|
914
1016
|
```bash
|
|
915
1017
|
mkdir -p scripts/ci
|
|
916
|
-
cp .bkit/templates/scripts/ci/bkit-machine-lock.sh scripts/ci/
|
|
1018
|
+
cp .bkit/templates/scripts/ci/bkit-machine-lock.sh .bkit/templates/scripts/ci/bkit-test-awake.mjs scripts/ci/
|
|
917
1019
|
```
|
|
918
1020
|
|
|
919
1021
|
<!-- prettier-ignore -->
|
|
@@ -930,10 +1032,27 @@ cp .bkit/templates/scripts/ci/bkit-machine-lock.sh scripts/ci/
|
|
|
930
1032
|
- `release_local_stack_lock [name]` frees the lock early.
|
|
931
1033
|
- `local_stack_lock_holder [name]` prints the holder, or every holder of `tests` slots.
|
|
932
1034
|
- `local_stack_lock_file [name]` prints the lock file path.
|
|
933
|
-
- `run ["<who>"] [--lock <name>] -- <command> [args…]` passes the command's exit status on. Exit 2 means usage, 73 means the lock could not be taken (including lock order),
|
|
1035
|
+
- `run ["<who>"] [--lock <name>] -- <command> [args…]` passes the command's exit status on. Exit 2 means usage, 73 means the lock could not be taken (including lock order), 75 means the wait gave up, and 124 means the hold limit stopped the command. Omit `<who>` to use `LOCAL_STACK_LOCK_WHO`, else `npm_lifecycle_event`, else `run`.
|
|
1036
|
+
- Hold limit: a `run` that took the `tests` lock holds it at most `LOCAL_STACK_LOCK_HOLD_S` seconds (whole number >= 1, default 3600; any other value falls back to 3600 with one note). The limit counts every second the command runs, including time it spends waiting inside the lock.
|
|
1037
|
+
- At the limit, `run` sends TERM to the command and every process started under it, then KILL to those still running after `LOCAL_STACK_LOCK_HOLD_GRACE_S` seconds (whole number >= 0, default 10). It then frees the lock, prints a `[machine-lock]` line naming the holder, the limit and the time held, and exits 124. A command that ends before the stop keeps its own exit status.
|
|
1038
|
+
- Only `run` enforces the limit, and only the `run` that took the `tests` lock. These have no limit:
|
|
1039
|
+
- every other named lock and the unnamed stack lock, since a run may hold those for hours;
|
|
1040
|
+
- a nested `run` that reuses its live parent's lock;
|
|
1041
|
+
- `CI=true` / `CI=1`, which takes no lock;
|
|
1042
|
+
- a runner that sources the script and calls `take_local_stack_lock`.
|
|
1043
|
+
- The holder enforces the limit because the OS never hands the lock to a waiter while the holder is alive. A run waiting for the lock takes it within a second of the stop.
|
|
1044
|
+
- Under the limit, the command must be a program on `PATH`, because `run` starts it with `exec`. A shell function or builtin fails with exit 127 or 126; wrap shell code in `sh -c '…'`.
|
|
1045
|
+
- `run` starts the command under `node bkit-test-awake.mjs --hold-s <limit> --grace-s <grace> --stopped-file <file>` from the script's folder, and that supervisor does the stop, creates the file and exits 124. `run` reads exit 124 as a hold-limit stop only when that file exists; otherwise 124 is the command's own. A supervisor that cannot create the file still stops the command, and `run` reports that 124 as the command's own. Without `node` on `PATH`, or with that file missing or without `--hold-s`, `run` frees the lock, names the file, writes `outcome=refused` and exits 73.
|
|
1046
|
+
- If the supervisor itself is killed, `run` frees the lock and exits with its status while the command may still be running.
|
|
1047
|
+
- The supervisor lists the processes under the command once a second with the first `ps` on `PATH` and its `lstart` column (procps on Linux), so it also stops a process whose parent has exited. Without a `ps` that prints `lstart`, such as a slim image with no procps or a BusyBox `ps`, it prints one note and the limit stops only the command itself, not the processes under it.
|
|
1048
|
+
- A process whose parent exits within a second of starting it may survive the stop. It does not hold the lock, so the lock is still freed, but it may keep the caller's output pipe open, and a caller that reads that pipe to its end then waits for that process.
|
|
1049
|
+
- The command keeps the caller's process group and stdin, so it still reads the terminal and gets Ctrl-C. TERM, INT and HUP sent to `run` are passed on to the command (INT only when `run` does not have the terminal, since Ctrl-C reaches the command directly); `run` keeps the lock until the command ends, then exits with the signal's status. A signal that arrives once the hold-limit stop has started is not passed on, and the exit stays 124.
|
|
1050
|
+
- Give one long gate a longer limit by prefixing that gate's `package.json` script, for example `"bkit:gate:e2e": "LOCAL_STACK_LOCK_HOLD_S=10800 bash scripts/ci/bkit-machine-lock.sh run --lock tests -- <gate command>"`. Every other gate keeps the 3600-second default.
|
|
1051
|
+
- Status file: when `LOCAL_STACK_LOCK_STATUS_FILE` names a path and `run` exits 75, 73 or 124, `run` writes that file (a temp file beside it, then a rename) as three lines: `lock=<name>`, `outcome=gave-up`, `outcome=refused` or `outcome=held-too-long`, and `holder=<each holder's note, joined by "; ">` (for `held-too-long`, the stopped run's own note). The caller reads the outcome from the exit code and this file, never from the printed lines. `run` unsets the variable for its command, so a nested wrapper never writes the caller's file. `bkit tests run`, `bkit tests changed` and `bkit branches push` create the file and read it.
|
|
1052
|
+
- `slots` prints `slots=N workers=N` for the current environment and exits 0; it is the one place the slot rule lives. `queue [--lock <name>]` prints one `<who> — <checkout>` line per waiting run and held place, in queue order, and exits 0 with no output when nobody waits. `jump [--lock <name>] <who> [<checkout>]` moves that run to the front: exit 0 printing its line, 1 when none matches, 3 when several match (printing them), 73 when the marker cannot be written. `queue` and `jump` default to the `tests` lock.
|
|
934
1053
|
- Named locks use `~/.cache/bkit/machine-lock/<name>.lock`, with no repository prefix. The holder line identifies the caller's checkout. A child inherits `LOCAL_STACK_LOCK_OWNER_<key>` and reuses only that named lock while its owner is alive.
|
|
935
|
-
- The `tests` lock has `BKIT_TEST_SLOTS` slots (whole number >= 1
|
|
936
|
-
- Taking `tests` exports `BKIT_TEST_WORKERS` = max(1, floor(cores / slots) - 1). Pass it to your runner, for example `vitest run --maxWorkers="$BKIT_TEST_WORKERS"` inside the wrapped command. Cores come from `getconf _NPROCESSORS_ONLN`, else `nproc`, else `sysctl -n hw.ncpu`, else 1.
|
|
1054
|
+
- The `tests` lock has `BKIT_TEST_SLOTS` slots (whole number >= 1). The default is 2 slots on a machine with 8 or more cores when the run is local, else 1; every other runtime defaults to 1 slot. A run is not local when `BKIT_RUNTIME` is set to anything but `LOCAL`; with `BKIT_RUNTIME` unset, it is not local when `.bkit/.runtime-cursor` exists in the main checkout or `CLAUDE_CODE_REMOTE` is set to anything but empty, `false`, `0` or `no` in any case. An invalid value falls back to that default with one note. Set `BKIT_TEST_SLOTS` per machine, never per repo. The value is per process: set it in every place runs start from (the shell profile and each host's user-level settings) or nowhere, because runs that read different values can hold `tests` slots at once. Slot 1 uses `tests.lock`; later slots use `tests.<k>.lock`. The waiting note names every holder.
|
|
1055
|
+
- Taking `tests` exports `BKIT_TEST_WORKERS` = max(1, floor(cores / slots) - 1), and `slots` prints the same number before any lock is taken. Pass it to your runner, for example `vitest run --maxWorkers="$BKIT_TEST_WORKERS"` inside the wrapped command. Cores come from `getconf _NPROCESSORS_ONLN`, else `nproc`, else `sysctl -n hw.ncpu`, else 1.
|
|
937
1056
|
- Take locks in this order: `tests`, other named locks, then the unnamed stack lock. A request for `tests` while this shell or a live parent holds another lock is refused. A request for a named lock while holding the stack lock is also refused.
|
|
938
1057
|
- The unnamed stack lock keeps `~/.cache/bkit/local-stack-lock/<stack>.lock` and `LOCAL_STACK_LOCK_OWNER` / `LOCAL_STACK_LOCK_PID`. A consumer's adopted copy keeps working and excludes this copy on the same stack.
|
|
939
1058
|
- `<stack>` is `BKIT_LOCAL_STACK`, else the main checkout's folder name, so every worktree finds the same lock.
|
|
@@ -942,6 +1061,15 @@ cp .bkit/templates/scripts/ci/bkit-machine-lock.sh scripts/ci/
|
|
|
942
1061
|
- Lock paths use `$XDG_CACHE_HOME/bkit/` when set. A small Perl process holds the file lock and exits within a second of its caller, however the caller ends.
|
|
943
1062
|
- Wait: `LOCAL_STACK_LOCK_WAIT_S` when set, else 60 seconds without a TTY, else 3600 seconds. Waiting notes name the budget and holders once a minute; the give-up line names the holder again.
|
|
944
1063
|
- A named release records held seconds by checkout in `<name>.last`, with one tab-separated line per checkout. A waiting note and give-up line name the current holder's `last run took <N>m<N>s`, or `no earlier run`.
|
|
1064
|
+
- Waiters are served in the order they started waiting. Each wait-mode take keeps a flock-held ticket in `<name>.queue/` beside its lock file (the unnamed stack lock uses `<stack>.queue/`), named `<monotonic seconds>-<pid>`, and a waiter tries the lock only when no earlier live ticket blocks it. Every lock shares this queue, including each `tests` slot.
|
|
1065
|
+
- A ticket holds the waiter's line on its first line and `slots=N`, the slots it asks for, on its second. A waiter may take slot `k` only while no live ticket ahead of it asks for `k` or more slots, so waiters asking for the same count keep arrival order, a 1-slot waiter ahead never blocks slot 2, and a ticket with no `slots=` line asks for every slot.
|
|
1066
|
+
- A ticket whose waiter died, or whose helper was killed, is skipped and removed; a waiter that gives up or is signalled drops its ticket.
|
|
1067
|
+
- A waiter that gives up leaves its ticket as `<ticket>.held` for 120 seconds; the same run (same name and checkout) asking again within that time takes its place back. Older held places are deleted. Names that are neither tickets nor held places are left alone.
|
|
1068
|
+
- The waiting note names the place in line (`2nd in line`). `try_local_stack_lock` never joins the line and reports busy (`N waiting in line`) while any live ticket exists, even when the lock is free.
|
|
1069
|
+
- A waiter stopped (for example with `SIGSTOP`) while first in line holds the line: `ls` the queue folder to see who is first.
|
|
1070
|
+
- A queue folder that cannot be created, or a ticket that cannot be written, refuses the take with the queue path (`run` exits 73).
|
|
1071
|
+
- `bkit tests jump <run>` asks the template's copy of the script (`jump --lock tests`) to move one waiting run to the front of the `tests` line by writing a `<ms>.jump` marker in `tests.queue/`; it exits 3 when the script cannot read the queue or write the marker. The holder keeps the lock, the newest jump goes first, and the marker goes when that run takes the lock or no waiting run matches it. `--checkout <path>` picks one when several runs share the name. Every use needs the human's approval (a host `ask`; denied on Codex, which cannot ask), so an agent cannot approve its own jump.
|
|
1072
|
+
- `bkit upgrade` replaces an unedited copy of `scripts/ci/bkit-machine-lock.sh` from a shipped release with the current template. It leaves an edited copy alone and warns to merge the template by hand when the copy has no queue, never names `LOCAL_STACK_LOCK_STATUS_FILE` or has no `LOCAL_STACK_LOCK_HOLD_S` hold limit; until merged, a wait that gives up reads as a gate failure (exit 1) instead of exit 81, and a hung run holds the lock until someone stops it. Beside such a lock copy it writes a missing `scripts/ci/bkit-test-awake.mjs` from the template and replaces an unedited shipped copy; it leaves an edited copy without `--hold-s` alone and warns to merge the template by hand, and until then every `run` that holds the tests lock is refused with exit 73.
|
|
945
1073
|
- `CI=true` / `CI=1` makes every lock a no-op.
|
|
946
|
-
- `bkit tests run` and `bkit tests changed` pass `--lock-wait-s
|
|
1074
|
+
- `bkit tests run` and `bkit tests changed` pass `--lock-wait-s`, their run name and a fresh `LOCAL_STACK_LOCK_STATUS_FILE` to a wrapped gate; exit 75 with `lock=tests` and `outcome=gave-up` in that file maps to 81 with `lockHolder` from `holder=`, and exit 73 with `outcome=refused` or exit 124 with `outcome=held-too-long` maps to 4 (could not run: a `test-run` row with a null verdict, never `FAIL`). Without that file, a 75, 73 or 124 is a gate failure (exit 1). A lock wait writes no `test-run` status row. Light runs (`red`, `green`, `bkit:test:file`) take no tests lock. Nested wraps reuse their live parent's tests lock. See `.bkit/workflows.md` § Test and release mechanics for host wait budgets.
|
|
947
1075
|
- Fix hints and docs name the locked scripts, never the raw command (`supabase db reset`, `docker compose down`), because the raw command skips the lock. See `.agents/rules.md` § Shared local stack.
|
|
@@ -16,7 +16,28 @@
|
|
|
16
16
|
> - Add its value to the enum in `.bkit/core/engine/install/manifest.ts`.
|
|
17
17
|
> - Document its MCP server under `mcpServers.<name>` in `.bkit/shared/.mcp.json` and `.bkit/shared/.cursor/mcp.json`.
|
|
18
18
|
> - Add a `<!-- bkit:tracker <name> -->` block after the last tracker block at every call site, and extend `GROUP_RE` in `.bkit/core/engine/render/trackers.ts`.
|
|
19
|
-
> -
|
|
19
|
+
> - No `none` marker exists. No-tracker content goes in a `false` block.
|
|
20
|
+
|
|
21
|
+
## Workflow comment delivery
|
|
22
|
+
|
|
23
|
+
The engine may append routine reports to its own eligible progress comment. Ownership comes from an explicit repo-info session or an exact workflow run, never another active run. A later human or unrelated comment, missing ownership evidence, or a capacity rollover starts a new comment. Attention reports and terminal summaries always use new comments.
|
|
24
|
+
|
|
25
|
+
The optional progress cache and run association live under the repository's Git-common `bkit-outbox` directory, shared by linked worktrees. Losing this state starts fresh. Remote text can confirm an owned comment, but never becomes the source of a replacement body. Reconciliation reads a bounded newest-created window, including paginated provider responses.
|
|
26
|
+
|
|
27
|
+
Preparation, delivery, reconciliation, receipt and friction failures are nonfatal. When `tracker.done` is false and `commentFile` exists, attempt one new MCP comment from that file byte-for-byte. MCP fallback never edits prior tracker content. Record best-effort redacted friction and continue substantive work even when the file or fallback is unavailable.
|
|
28
|
+
|
|
29
|
+
### Verified provider contracts
|
|
30
|
+
|
|
31
|
+
Live contract evidence version 1 verified the following boundaries through the production transports. Every selected body budget counts the complete Markdown source in UTF-16 code units, including markers and part labels. These budgets are conservative delivery ceilings, rather than promises of each provider's maximum.
|
|
32
|
+
|
|
33
|
+
<!-- prettier-ignore -->
|
|
34
|
+
| Provider | Selected body budget | Observed counting boundary | Inspection and edit contract |
|
|
35
|
+
| --- | --- | --- | --- |
|
|
36
|
+
| GitHub | 65,536 | 262,144 UTF-8 body bytes accepted; the next byte rejected for ASCII and non-BMP text. | REST create/edit and GraphQL read agree on numeric comment/author IDs, timestamps and Markdown fingerprints. `last`/`before` pagination retains newest-created order after an older edit. |
|
|
37
|
+
| Linear | 100,000 | 100,000 Unicode scalars accepted; the next scalar rejected for ASCII and non-BMP text. UTF-16 counting stays conservative. | GraphQL create/edit/read return stable comment/user IDs, timestamps and Markdown fingerprints. Cursor pages are sorted by creation time before selecting the newest comments. |
|
|
38
|
+
| Jira Rovo | 32,767 | The selected ASCII/non-BMP payloads pass. Markdown-to-ADF conversion changes the raw-source boundary; larger payloads can fail with `CONTENT_LIMIT_EXCEEDED`. No universal raw-source maximum is claimed. | Deployed tool schemas accept ID-based edits and `responseContentFormat: markdown`, `view: evidence`, creation ordering and offset pagination. Require returned Markdown format, stable author/comment IDs and matching fingerprints before editing. |
|
|
39
|
+
|
|
40
|
+
All three preserve the generated h6 marker on the tested bodies. Repeated reads remain stable, an external edit starts fresh progress, and a terminal report creates a separate comment. Discarded acknowledgments can be recognized by bounded reads; inconclusive recognition tries a new comment and can duplicate an accepted report. Exhausted writes produce real best-effort friction and allow later reporting to continue. These probes do not establish universal notification silence: GitHub and Linear subscriber settings and Jira project notification schemes still apply.
|
|
20
41
|
|
|
21
42
|
## Marker contract
|
|
22
43
|
|
|
@@ -95,9 +116,9 @@ This renders `N. <body>` when a tracker is wired, and `N. _No tracker connected,
|
|
|
95
116
|
| `issue-update-failed` | Failure Path additive `bkit:failed` | `issue_write` labels | `save_issue_label` per new label, then `save_issue` labels, then `save_issue` state `bkit.tracker.linear.review` | `editJiraIssue` full label set, then transition to `bkit.tracker.jira.review` | skip |
|
|
96
117
|
| `issue-update-merged` | Ship terminal — `bkit:merged` + In Review (issue left open; human closes) | `issue_write` `bkit:merged` (no close) | `save_issue_label` per new label, then `save_issue` labels, then `save_issue` state `bkit.tracker.linear.review` | `editJiraIssue` full label set, then transition to `bkit.tracker.jira.review` | skip |
|
|
97
118
|
| `issue-update-status` | Projects v2 board status (best-effort) | `projects_write` add / update item | no-op (state carries) | no-op (status carries) | skip |
|
|
98
|
-
| `comment-post-step` |
|
|
119
|
+
| `comment-post-step` | engine-owned routine progress; create-only fallback | `add_issue_comment` | `save_comment` without `id` | `addOrEditJiraIssueComment` without `commentId` | skip |
|
|
99
120
|
| `issue-blockers-check` | Gate on open blockers | parse body marker → read states | `get_issue` relations | JQL `linkedIssues(KEY, "is blocked by") AND statusCategory != Done` | skip |
|
|
100
|
-
| `kill-switch-check` |
|
|
121
|
+
| `kill-switch-check` | Re-read the labels after the push (build Step 16, debug Step 11); the run is already finished, so an absent `bkit:auto` stops nothing and only adds a line to the final message; skipped when `ISSUE_ID` empty | label check | label check | label check | inactive |
|
|
101
122
|
| `pr-body-metadata` | Parse PR-body issue / FID marker; FID-only marker (no issue) → `issueId: null`, `/bkit-auto` fails closed | `pull_request_read` + parse | same (GitHub PR) | same (GitHub PR) | FID-only, no fail-closed |
|
|
102
123
|
| `pr-body-marker` | Literal PR-body marker line; no issue → `<!-- bkit:fid={FID} -->` alone | `<!-- bkit:issue=#{ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:issue={ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:issue={ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:fid={FID} -->` |
|
|
103
124
|
|
|
@@ -118,7 +139,7 @@ Workflows read an issue's body and comments (`bkit issues text`), never its titl
|
|
|
118
139
|
|
|
119
140
|
- Success Criteria: <=5 bullets, each an observable outcome.
|
|
120
141
|
- Edge Cases: `| Scenario | Expected Behavior |`.
|
|
121
|
-
- Derived Test Matrix: `| Test description | Type | Target file
|
|
142
|
+
- Derived Test Matrix: `| Test description | Type | Target file |` in the issue; the plan form is the four columns `Test description | Type | Target file | Task`, with `Task` last. Type = the lowest tier that exercises the test, named as in `docs/testing.md`. Exactly one task covers each row.
|
|
122
143
|
- Tasks, in build order, as task group and task blocks (`docs/templates/bkit-plan.md` § Agent Execution Runbook), sized by `package.json` `bkit.workflows.tasks`:
|
|
123
144
|
- Each group holds <= `bkit.workflows.tasks.maxPerGroup` tasks (default 5) and <= `bkit.workflows.tasks.maxTestsPerGroup` `TEST FIRST` tests (default 25).
|
|
124
145
|
- Each task has 1 to `bkit.workflows.tasks.maxTestsPerTask` tests (default 10) across <= `bkit.workflows.tasks.maxTestFilesPerTask` test files (default 3), or `n/a — {reason}` for docs, config, a pure refactor, or E2E / @live only.
|
|
@@ -179,7 +200,7 @@ Workflows read an issue's body and comments (`bkit issues text`), never its titl
|
|
|
179
200
|
| design `Suggested Plans` (`P-N`; 2+ → design summary next step; 1 → planned on the design's own issue) | one issue per plan, never per workstream; title = plan name; body = its deliverable and covered workstream scopes, spec left to design; filed in `Requires` order | `**Parent design:**` line; `**Workstreams:**` line = its `Covers` ids; blocked-by block = plan issues filed for its `Requires` (linear → `blockedBy` relation; jira → `Blocks` link, `inwardIssue` = blocker) |
|
|
180
201
|
| roadmap item with no issue (ledger row, audit candidate) | by recommended command, as audit row | ledger `key` / report path in References |
|
|
181
202
|
|
|
182
|
-
**Audit parent** — one standing issue per audit template, shared by every run of that template.
|
|
203
|
+
**Audit parent** — one standing issue per audit template, shared by every run of that template. No audit parent is opened per run, and none spans templates.
|
|
183
204
|
|
|
184
205
|
<!-- prettier-ignore -->
|
|
185
206
|
| Field | Value |
|
|
@@ -236,17 +257,29 @@ bkit supports Jira Cloud only. `ISSUE_ID` is the issue key (`PROJ-123`), which g
|
|
|
236
257
|
2. Each person opens https://id.atlassian.com/manage-profile/security/api-tokens → **Create API token with scopes** (not classic) → app **Atlassian MCP V2** (not **Jira**, not **Atlassian MCP**) → the Jira read / write / search scopes (`read:jira:agent-interface`, `write:jira:agent-interface`, `search:jira:agent-interface`). Copy the token, which is shown once, into `BKIT_JIRA_API_KEY` in `.bkit/.env`, then run `direnv allow`. The token works on MCP only, and the Jira REST API answers 401.
|
|
237
258
|
3. Run `bkit install --tracker=jira`, then set `bkit.tracker.jira.site` and `bkit.tracker.jira.project`. In Claude, approve the project `.mcp.json` once in an interactive `claude` session. Until then, `claude mcp list` shows "Pending approval".
|
|
238
259
|
|
|
260
|
+
### Authentication troubleshooting
|
|
261
|
+
|
|
262
|
+
The scoped **Atlassian MCP V2** token is a personal API token used as `Bearer` by bkit's Rovo transport. It needs no account email. The API-token management page alone does not identify the token's app or scopes. Jira REST guidance about `Basic` authentication with an email does not establish the authentication contract for this MCP endpoint.
|
|
263
|
+
|
|
264
|
+
For an authentication failure:
|
|
265
|
+
|
|
266
|
+
1. Read this section and the project's active `docs/knowledge.jsonl` entries before asking for credentials. Check related tracker decisions and comments when the owner says the setup worked previously.
|
|
267
|
+
2. Check that the running process loads `BKIT_JIRA_API_KEY` from the intended `.bkit/.env`, including in a linked worktree. After a credential update, compare the loaded and saved values without printing either value, and check for surrounding whitespace. Report presence and equality only.
|
|
268
|
+
3. Verify the setup above: the token's app and scopes, the org's API-token permission, the `/v2/mcp` endpoint, the `Bearer` header and a non-default `User-Agent`. A scripted probe must use the engine's `initialize` handshake before tool calls.
|
|
269
|
+
4. **If** initialization still returns HTTP 401 with `invalid_token` → record that the endpoint rejected the configured credential and which checks passed. Ask the owner to verify or replace the scoped token locally. Do not infer a missing email, switch to `Basic`, or add an email setting from this response. Tool schemas and write behaviour remain unverified until authentication succeeds.
|
|
270
|
+
|
|
239
271
|
**Behaviour workflows rely on:**
|
|
240
272
|
|
|
241
273
|
- Status changes only by transition. Workflows list the issue's transitions (`executeRead` `listJiraIssueTransitions`) and fire the one whose `to.name` = the target status. When none matches, the status change is `Unapplied`, and the labels still land. Basic team-managed boards may lack `In Review`, so set `bkit.tracker.jira.review` to a status the board has.
|
|
242
274
|
- Labels: `getJiraIssue` returns them only with `view: "evidence"` (or `"full"`). `editJiraIssue` replaces the whole set. Jira creates a label on first use. Stored labels are case-sensitive, and JQL search is not.
|
|
243
275
|
- Comments are posted as markdown, stored as Atlassian Document Format, and read back as markdown with the same meaning but not the same bytes (`-` bullets → `*`, `*em*` → `_em_`, extra blank lines; checkboxes and `> [!NOTE]` alerts come back escaped). One comment that Jira cannot express in markdown (a mention, an image, a panel) turns its whole page to HTML (`appliedContentFormat: "html"`), so reads by the engine and by the MCP fallback re-read that page one comment per call. A comment holds at most 32,767 characters, so the engine splits a longer one at line breaks into consecutive comments, each opening with `###### bkit:generated` and then `_(part i/n)_`.
|
|
244
276
|
- Blockers use the native `Blocks` link. `createJiraIssueLink` reads backwards: `inwardIssue` = the blocker, and `outwardIssue` = the blocked issue.
|
|
245
|
-
-
|
|
277
|
+
- No type labels exist: the issue type (Bug / Task / Story) carries the type.
|
|
246
278
|
|
|
247
279
|
<!-- prettier-ignore -->
|
|
248
280
|
| Symptom | Fix |
|
|
249
281
|
| --- | --- |
|
|
282
|
+
| HTTP 401 with `invalid_token` during initialization | Follow § Authentication troubleshooting; the response alone does not identify why the credential was rejected. |
|
|
250
283
|
| Only 4 tools listed (`getTeamworkGraphContext` …), no Jira tools | URL `/v2/mcp`, not `/v1/mcp` |
|
|
251
284
|
| Every call: `Cloud id: … isn't explicitly granted by the user` | Scoped **Atlassian MCP V2** token sent as `Bearer`, not classic token or `Basic` |
|
|
252
285
|
| `missing the scope claim` | Classic token → create token with scopes |
|