@cbartens/bkit 5.3.0 → 5.5.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 +20 -7
- package/.bkit/core/.agents/docs.md +1 -1
- package/.bkit/core/.agents/rules.md +14 -9
- package/.bkit/core/.bkit/README.md +19 -6
- package/.bkit/core/.bkit/cloud.md +77 -46
- package/.bkit/core/.bkit/comparison.md +3 -3
- package/.bkit/core/.bkit/install.md +21 -18
- package/.bkit/core/.bkit/lite.md +6 -6
- package/.bkit/core/.bkit/pipeline.md +6 -3
- package/.bkit/core/.bkit/prompts.md +14 -10
- package/.bkit/core/.bkit/providers.md +7 -7
- package/.bkit/core/.bkit/templates.md +46 -10
- package/.bkit/core/.bkit/trackers.md +92 -38
- package/.bkit/core/.bkit/workflows.md +140 -116
- package/.bkit/core/AGENTS.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
- 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 +2 -2
- 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 +4 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-issues.md +25 -8
- package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
- package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -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 +11 -9
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/engine/checks/after/auth.ts +88 -45
- package/.bkit/core/engine/checks/after/github.ts +18 -5
- package/.bkit/core/engine/checks/after/index.ts +1 -1
- package/.bkit/core/engine/checks/after/tools.ts +1 -1
- package/.bkit/core/engine/checks/before/env.ts +28 -18
- package/.bkit/core/engine/checks/before/mcp.ts +4 -2
- package/.bkit/core/engine/checks/status-holes.ts +0 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +31 -2
- package/.bkit/core/engine/checks/tips/index.ts +49 -27
- package/.bkit/core/engine/cli.ts +27 -18
- package/.bkit/core/engine/commands/ci/ci.ts +107 -0
- package/.bkit/core/engine/commands/comply.ts +25 -16
- package/.bkit/core/engine/commands/install/install.ts +11 -4
- package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
- package/.bkit/core/engine/commands/land.ts +156 -0
- package/.bkit/core/engine/commands/lib.ts +10 -8
- package/.bkit/core/engine/commands/registry.ts +2 -0
- package/.bkit/core/engine/commands/tips.ts +7 -3
- package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
- package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
- package/.bkit/core/engine/commands/workflow/issues.ts +106 -42
- package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
- package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
- package/.bkit/core/engine/commands/workflow/prs.ts +14 -3
- package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +53 -54
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
- package/.bkit/core/engine/commands/workflow/status.ts +33 -11
- package/.bkit/core/engine/commands/workflow/steps.ts +26 -17
- package/.bkit/core/engine/commands/workflow/workflows.ts +442 -269
- package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
- package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
- package/.bkit/core/engine/install/manifest.ts +31 -10
- package/.bkit/core/engine/install/modules/cloud.ts +3 -1
- package/.bkit/core/engine/install/modules/core.ts +97 -4
- package/.bkit/core/engine/install/modules/opencode.ts +5 -0
- package/.bkit/core/engine/install/placeholders.ts +13 -17
- package/.bkit/core/engine/install/write.ts +37 -1
- package/.bkit/core/engine/render/trackers.ts +35 -23
- package/.bkit/core/engine/shared/egress.ts +6 -0
- package/.bkit/core/engine/shared/settings.ts +96 -1
- package/.bkit/core/engine/shared/timeouts.ts +8 -7
- package/.bkit/core/hooks/guardrails-tiers.js +1 -1
- package/.bkit/core/prompts/bkit-audit-generate.md +80 -7
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
- package/.bkit/core/prompts/bkit-design-generate.md +2 -1
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
- package/.bkit/core/prompts/bkit-utility-update-failures.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +4 -2
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +12 -5
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
- package/.bkit/core/workflows/bkit-auto.md +19 -6
- package/.bkit/core/workflows/bkit-build.md +64 -22
- package/.bkit/core/workflows/bkit-debug.md +72 -28
- package/.bkit/core/workflows/bkit-design.md +101 -37
- package/.bkit/core/workflows/bkit-plan.md +82 -31
- package/.bkit/core/workflows/bkit-ship.md +127 -108
- package/.bkit/shared/.bkit/.env.example +8 -0
- package/.bkit/shared/.claude/bkit-cloud.md +12 -12
- package/.bkit/shared/.claude/settings.json +4 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
- package/.bkit/shared/.cursor/mcp.json +11 -4
- package/.bkit/shared/.mcp.json +11 -4
- package/.bkit/shared/.opencode/opencode.json +2 -0
- package/.bkit/shared/docs/deployments.md +44 -29
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/testing.md +3 -3
- package/.bkit/shared/gitignore +1 -2
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
- package/.bkit/templates/.github/renovate.json5 +1 -1
- package/.bkit/templates/.github/workflows/bkit-ci.yml +29 -56
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
- package/.bkit/templates/.husky/pre-commit +10 -4
- package/.bkit/templates/.husky/pre-push +69 -12
- package/.bkit/templates/.lintstagedrc.json +5 -1
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
- package/CHANGELOG.md +85 -1
- package/README.md +102 -100
- package/dist/checks/after/auth.js +81 -45
- package/dist/checks/after/github.js +17 -5
- package/dist/checks/after/index.js +1 -1
- package/dist/checks/after/tools.js +1 -1
- package/dist/checks/before/env.js +24 -17
- package/dist/checks/before/mcp.js +4 -2
- package/dist/checks/status-holes.js +0 -1
- package/dist/checks/tips/catalogue.js +28 -2
- package/dist/checks/tips/index.js +44 -28
- package/dist/cli.js +27 -19
- package/dist/commands/ci/ci.js +100 -0
- package/dist/commands/comply.js +20 -13
- package/dist/commands/install/install.js +10 -4
- package/dist/commands/install/uninstall.js +42 -0
- package/dist/commands/land.js +129 -0
- package/dist/commands/lib.js +9 -6
- package/dist/commands/registry.js +2 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +300 -243
- package/dist/commands/workflow/disk.js +452 -0
- package/dist/commands/workflow/fids.js +22 -15
- package/dist/commands/workflow/issues.js +90 -41
- package/dist/commands/workflow/ledgers.js +26 -11
- package/dist/commands/workflow/locks.js +35 -130
- package/dist/commands/workflow/prs.js +8 -3
- package/dist/commands/workflow/repo.js +5 -0
- package/dist/commands/workflow/roadmap.js +52 -57
- package/dist/commands/workflow/runtime.js +3 -2
- package/dist/commands/workflow/status.js +32 -12
- package/dist/commands/workflow/steps.js +20 -13
- package/dist/commands/workflow/workflows.js +397 -251
- package/dist/commands/workflow/workstreams.js +3 -2
- package/dist/commands/workflow/worktrees.js +11 -1
- package/dist/install/manifest.js +30 -10
- package/dist/install/modules/cloud.js +3 -1
- package/dist/install/modules/core.js +95 -5
- package/dist/install/modules/opencode.js +6 -0
- package/dist/install/placeholders.js +13 -19
- package/dist/install/write.js +26 -2
- package/dist/render/trackers.js +34 -20
- package/dist/shared/egress.js +6 -0
- package/dist/shared/settings.js +44 -0
- package/dist/shared/timeouts.js +8 -7
- package/package.json +11 -2
|
@@ -37,6 +37,7 @@ Adoption order = `bkit tips` order. Sections below: install steps and traps.
|
|
|
37
37
|
| 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
38
|
| Prettier tables | One edited cell = one changed row in the diff. | A one-word table edit diffs as the whole table. |
|
|
39
39
|
| 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
|
+
| 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. |
|
|
40
41
|
| Cursor editor + cloud agent | Format-on-save, recommended extensions, Cursor cloud-agent image. | Cursor edits miss project formatting; no Cursor cloud agent. |
|
|
41
42
|
| Launchd GUI env | macOS apps opened from the Dock get the same tokens as the terminal. | Dock-launched editors start signed out. |
|
|
42
43
|
|
|
@@ -46,7 +47,7 @@ Adoption order = `bkit tips` order. Sections below: install steps and traps.
|
|
|
46
47
|
| Tool | Copy from | To | Output you commit |
|
|
47
48
|
| --- | --- | --- | --- |
|
|
48
49
|
| CI workflow | `.bkit/templates/.github/workflows/bkit-ci.yml` | `.github/workflows/bkit-ci.yml` | that file |
|
|
49
|
-
| CI scripts | `.bkit/templates/scripts/ci/` | `scripts/ci/` | the scripts you adopt (`lanes/resolve-push-base.mjs`; `check-accepted-divergences.mjs` + `accepted-divergences.json`; `check-dependency-audit.mjs` + `accepted-advisories.json`). `check-capstone.mjs` + `check-capstone.test.mjs` are required with `bkit-ci.yml`, not optional |
|
|
50
|
+
| CI scripts | `.bkit/templates/scripts/ci/` | `scripts/ci/` | the scripts you adopt (`lanes/resolve-push-base.mjs`; `lanes/check-tree-cache.mjs` + `.test.mjs`, which `bkit-ci.yml`'s `Check Tree Cache` runs; `check-accepted-divergences.mjs` + `accepted-divergences.json`; `check-dependency-audit.mjs` + `accepted-advisories.json`). `check-capstone.mjs` + `check-capstone.test.mjs` are required with `bkit-ci.yml`, not optional |
|
|
50
51
|
| Cloud-agent workflow | `.bkit/templates/.github/workflows/bkit-cloud.yml` | `.github/workflows/bkit-cloud.yml` | that file |
|
|
51
52
|
| Git hooks (Husky) | `.bkit/templates/.husky/pre-commit`, `.bkit/templates/.husky/pre-push` | `.husky/pre-commit`, `.husky/pre-push` | both files |
|
|
52
53
|
| Prettier ignore list | `.bkit/templates/.prettierignore` | `.prettierignore` | that file |
|
|
@@ -67,6 +68,7 @@ Adoption order = `bkit tips` order. Sections below: install steps and traps.
|
|
|
67
68
|
| Secrets sync | `.bkit/templates/scripts/secrets/` | `scripts/secrets/` | both files; never `bkit-secrets-state.json` |
|
|
68
69
|
| Prettier tables | `.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs` | `scripts/prettier/` | that file |
|
|
69
70
|
| tmp/ prune | `.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs` | `scripts/cleanup/` | that file |
|
|
71
|
+
| 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 |
|
|
70
72
|
| Context-fetch blocks | `.bkit/templates/context/bkit-<provider>.md` | below `<!-- bkit:end -->` in `.agents/context.md` | the blocks you use |
|
|
71
73
|
| Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file |
|
|
72
74
|
|
|
@@ -75,7 +77,7 @@ Placeholders. Copies keep them raw; replace each in your copy:
|
|
|
75
77
|
<!-- prettier-ignore -->
|
|
76
78
|
| Placeholder | In | Put | Typical value |
|
|
77
79
|
| --- | --- | --- | --- |
|
|
78
|
-
| `{{DEFAULT_BRANCH}}` | `bkit-ci.yml` (`on.push` / `on.pull_request` branches; stub comments), `bkit-trivy.yml` (`on.push` / `on.pull_request` branches) | your
|
|
80
|
+
| `{{DEFAULT_BRANCH}}` | `bkit-ci.yml` (`on.push` / `on.pull_request` branches; stub comments), `bkit-trivy.yml` (`on.push` / `on.pull_request` branches) | your production branch | `origin/HEAD` unless it is `dev`, else `main` |
|
|
79
81
|
| `{{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` |
|
|
80
82
|
| `{{CLOUD_RUNNER}}` | `bkit-cloud.yml` (`runs-on`, all three jobs) | a runner label | `ubuntu-latest` |
|
|
81
83
|
| `{{SCRIPT_PATH}}` | `ai.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` |
|
|
@@ -147,6 +149,7 @@ bkit seeds only the `bkit:gate:*` / `bkit:deps:*` names (add-if-missing). The to
|
|
|
147
149
|
| Gate (default) | Chains | Needs |
|
|
148
150
|
| --- | --- | --- |
|
|
149
151
|
| `bkit:gate:format` | `pnpm lint-staged` | lint-staged devDep + `.lintstagedrc.json` + prettier |
|
|
152
|
+
| `bkit:gate:min` | `format:check`, `lint:prose`, `slop:delta` | the scripts below + any test reading a min-push file |
|
|
150
153
|
| `bkit:gate:static` | `typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta` | the scripts below |
|
|
151
154
|
| `bkit:gate:static-unit` | `bkit:gate:static` + `test` | a `test` script |
|
|
152
155
|
| `bkit:gate:install-static-unit-build` | `pnpm install --frozen-lockfile` + `bkit:gate:static-unit` + `build` | a `build` script |
|
|
@@ -176,7 +179,7 @@ pnpm add -D prettier@^3.5.3 slop-scan@^0.3.0 lint-staged@^17.0.0 husky@^9.1.7
|
|
|
176
179
|
|
|
177
180
|
## CI workflow — `bkit-ci.yml`
|
|
178
181
|
|
|
179
|
-
Parallel lanes `bkit-tests-static` (typecheck, lint, prettier, Vale, slop, actionlint, `bkit check`) and `bkit-tests-unit`, joined by the `bkit-tests-check` capstone, plus the commented full CI scaffold reference for the other tiers. Workflows care: `/bkit-ship` waits on its runs and merges only when the `bkit.capstoneJob` job (default `bkit-tests-check`) is present and green at the head; `bkit setup protect-main` makes that job the required check; `bkit-cloud.yml` triggers on a workflow named `bkit-ci`. `bkit install` reads your copy for advisories (`
|
|
182
|
+
Parallel lanes `bkit-tests-static` (typecheck, lint, prettier, Vale, slop, actionlint, `bkit check`) and `bkit-tests-unit`, joined by the `bkit-tests-check` capstone, plus the commented full CI scaffold reference for the other tiers. Workflows care: `/bkit-ship` waits on its runs and merges only when the `bkit.capstoneJob` job (default `bkit-tests-check`) is present and green at the head; `bkit setup protect-main` makes that job the required check; `bkit-cloud.yml` triggers on a workflow named `bkit-ci`. `bkit install` reads your copy for advisories (`bkit-stub-*`, `ci-yml-missing-actionlint`, `ci-yml-capstone-contract-drift`). Reference: https://docs.github.com/en/actions.
|
|
180
183
|
|
|
181
184
|
- Install: nothing beyond the gate tool scripts above, a `test` script, and `packageManager` in `package.json` (`pnpm/action-setup` reads it; do not add `with: version:`).
|
|
182
185
|
- Adapt: `{{DEFAULT_BRANCH}}`, `{{NODE_VERSION}}`. Non-Node repo → replace the Node / pnpm setup, install and check steps with your stack's.
|
|
@@ -190,13 +193,13 @@ Parallel lanes `bkit-tests-static` (typecheck, lint, prettier, Vale, slop, actio
|
|
|
190
193
|
Post-CI router: CI pass on `feat/**` → `/bkit-ship`, fail → `/bkit-debug`; failed `dev` CI → `/bkit-debug {FID}`; `workflow_dispatch` runs any phase. A `context` job resolves phase + arg once, then two runner jobs, each skipped without its secret: `claude` (`claude-code-action`, https://github.com/anthropics/claude-code-action) and `opencode` (`opencode run`, https://opencode.ai/docs/github/). Runs bkit workflows; `bkit install --auto=claude|opencode` points at it. Full recipe: `.bkit/cloud.md` § Post-CI auto-routing.
|
|
191
194
|
|
|
192
195
|
- Install: `bkit install --auto=claude` (points at the `.claude/hooks/bkit-cloud-bootstrap.sh` template) or `--auto=opencode` (needs `--opencode=<provider>` first). Both need `--tracker=github`.
|
|
193
|
-
- Secrets: `ANTHROPIC_API_KEY` + the Claude GitHub App (`/install-github-app`) for `claude`; `OPENCODE_PROVIDER_KEY` for `opencode`. Repo Actions permissions: read and write, PR creation allowed.
|
|
196
|
+
- Secrets: `ANTHROPIC_API_KEY` (or keyless: `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables) + the Claude GitHub App (`/install-github-app`) for `claude`; `OPENCODE_PROVIDER_KEY` for `opencode`. Repo Actions permissions: read and write, PR creation allowed.
|
|
194
197
|
- Adapt: `{{CLOUD_RUNNER}}` in all three jobs.
|
|
195
198
|
- Traps: 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. The opencode install version is a plain argument; the `# renovate:` comment above it lets the example `renovate.json5` bump it. Keep the file out of updater `ignorePaths` so action pins refresh.
|
|
196
199
|
|
|
197
200
|
## Git hooks — Husky
|
|
198
201
|
|
|
199
|
-
`pre-commit` runs `bkit:gate:format`; `pre-push` runs `bkit:gate:static-unit` (`bkit:gate:static` on revert branches / commits), then `bkit check`, plus
|
|
202
|
+
`pre-commit` runs `bkit:gate:format`; `pre-push` 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), then `bkit check`, plus the CI-suppressing-token guards and the `tmp/` prune (§ tmp/ prune). Each hook ends by starting the disk prune (§ Disk prune). Workflows care: they commit and push without `--no-verify`, so a failing hook stops a workflow. One exception: the throwaway `.worktrees/_land-{FID}` checkout that lands bookkeeping on `dev` (docs, logs, ledgers, `[skip ci]`) runs no hooks and logs that it skipped them. Reference: https://typicode.github.io/husky/.
|
|
200
203
|
|
|
201
204
|
```bash
|
|
202
205
|
pnpm add -D husky@^9.1.7 # plus "prepare": "husky" (§ Gate tool scripts)
|
|
@@ -205,7 +208,12 @@ chmod +x .husky/pre-commit .husky/pre-push
|
|
|
205
208
|
|
|
206
209
|
- `.gitignore`: `.husky/_` (bkit's `.gitignore` block already lists it).
|
|
207
210
|
- 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.
|
|
208
|
-
-
|
|
211
|
+
- Min push: every file changed since each pushed commit left `origin/dev` (else `origin/main`) matches `bkit.minPushPaths` (`package.json` globs: `*` one folder, `**` any depth; default `docs/plans/**`, `docs/*.jsonl`, `.bkit/*.jsonl`; `[]` = off) → `bkit:gate:min` replaces the full gate; `MIN_PUSH=1`. `bkit ci min-push` decides from files, never `[skip ci]` (a typed label; GitHub reads the last commit only). No files / unreadable range / no ref list → full gate.
|
|
212
|
+
- Min-push paths: files no code, build or test reads. Never `docs/**` (a doc can be test input). A test reading a ledger → into `bkit:gate:min`.
|
|
213
|
+
- `[skip ci]` guards: feature branch → blocked only while a PR is open (workflows push `[skip ci]` code heads mid-run). `dev` / `main` → blocked unless a min push: GitHub skips CI for the whole push.
|
|
214
|
+
- Slow repo extras (Docker, database, build) → wrap in `if [ "$MIN_PUSH" != "1" ]; then … fi`.
|
|
215
|
+
- Traps: hooks run on every workflow commit; keep them to seconds (pre-commit) and deterministic checks that reach no deployed service (pre-push). Integration runs at pre-push once `bkit:gate:static-unit-integration` is declared (a local database in Docker is fine); E2E and `@live` belong in CI.
|
|
216
|
+
- Run each check once: nothing in `bkit:gate:format` that the push gate runs again (`gate-commit-repeats-push` advisory), and `pnpm test` (the unit tier) matches no `*.integration.test.*` file — a unit config with no integration exclude runs those tests in the unit gate and again in the integration gate.
|
|
209
217
|
|
|
210
218
|
## Prettier — `.prettierignore` first
|
|
211
219
|
|
|
@@ -226,6 +234,8 @@ Runs prettier over staged files. `bkit:gate:format` (the pre-commit hook) calls
|
|
|
226
234
|
pnpm add -D lint-staged@^17.0.0 prettier@^3.5.3
|
|
227
235
|
```
|
|
228
236
|
|
|
237
|
+
- Staged `docs/plans/**/*.md` + `docs/audits/**/*.md` (design, plan, audit docs) run `scripts/prettier/bkit-insert-ignore.mjs` before prettier → committed tables carry `<!-- prettier-ignore -->` and `| --- |` separators. Needs § Prettier tables copied; without it, commits touching those files fail.
|
|
238
|
+
- Globs must not overlap: lint-staged runs entries concurrently, so two entries writing one file race. Second entry negates the first.
|
|
229
239
|
- Adapt: add per-glob commands (eslint `--fix`, etc.) — keep them seconds-fast.
|
|
230
240
|
|
|
231
241
|
## Vale — prose lint, with House styles
|
|
@@ -433,17 +443,17 @@ PyPI name `serena-agent`, CLI `serena`. PyPI `serena` is an unrelated package.
|
|
|
433
443
|
|
|
434
444
|
## Issue forms — `.github/ISSUE_TEMPLATE/`
|
|
435
445
|
|
|
436
|
-
Issues are the first input every workflow reads. One form per way work starts; each form's intro names its next command. Section names, syntax and machine-read lines: `.bkit/trackers.md` § Issue shapes. GitHub tracker ONLY (Linear
|
|
446
|
+
Issues are the first input every workflow reads. One form per way work starts; each form's intro names its next command. Section names, syntax and machine-read lines: `.bkit/trackers.md` § Issue shapes. GitHub tracker ONLY (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.
|
|
437
447
|
|
|
438
448
|
<!-- prettier-ignore -->
|
|
439
449
|
| Form | Use when | Next step | Asks for |
|
|
440
450
|
| --- | --- | --- | --- |
|
|
441
451
|
| `bkit-idea.yml` | How it should work is still open | `/bkit-design #N` | problem, outcome, success criteria, constraints and non-goals, decisions already made, open questions |
|
|
442
|
-
| `bkit-change.yml` | What to build and "done" are known | `/bkit-plan #N`, or `/bkit-build #N` / `lite
|
|
452
|
+
| `bkit-change.yml` | What to build and "done" are known | `/bkit-plan #N`, or `/bkit-build #N` / `build:lite` with no plan | the plan in short: narrative, success criteria, edge cases, test matrix, tasks with `Done when` + `Test first`, breaking changes and names, out of scope |
|
|
443
453
|
| `bkit-bug.yml` | Something does not work | a test or CI run already fails → `/bkit-debug #N`; nothing fails yet → `/bkit-debug #N [repro]` | failing test or CI run, what happened, what should, repro steps, how often, affected area, where and when, evidence |
|
|
444
454
|
|
|
445
455
|
- Every form ends with References. The change form shows the lines workflows read: `**Parent design:**` and `**Audit reports:**` (plan), the blocked-by block (build). Other references are not fetched; write exact paths, ledger `key`s and `#N — title`.
|
|
446
|
-
- A change issue is the plan's source when no design or audit report exists: its narrative, success criteria, edge cases, test rows and tasks carry over verbatim. `/bkit-build` with no plan builds those tasks and checks each `Test first` test failed before its code; `lite
|
|
456
|
+
- A change issue is the plan's source when no design or audit report exists: its narrative, success criteria, edge cases, test rows and tasks carry over verbatim. `/bkit-build` with no plan builds those tasks and checks each `Test first` test failed before its code; `build:lite` checks nothing. Nothing ticks the boxes.
|
|
447
457
|
- Debug commits to the branch it runs on: start it on the branch the fix lands on.
|
|
448
458
|
- Copy the folder, commit on the default branch; GitHub reads forms from there only. Blank issues stay enabled.
|
|
449
459
|
- `labels:` applies `enhancement` / `bug` only when the repo has them; missing labels are skipped, never created. Never add `bkit:*` labels: workflows own them.
|
|
@@ -588,7 +598,7 @@ Prettier aligns markdown tables with no config toggle; one edited cell re-pads e
|
|
|
588
598
|
| `node scripts/prettier/bkit-insert-ignore.mjs` | Rewrite `.agents/`, `docs/`, `README.md` (or the paths given). |
|
|
589
599
|
| `node scripts/prettier/bkit-insert-ignore.mjs --check` | Write nothing; exit 1 if any file would change. Gate form. |
|
|
590
600
|
|
|
591
|
-
- Walks skip `skills/` trees (vendored), `docs/audits/`, `docs/plans/` (records, kept as written). A file named on the command line is always processed.
|
|
601
|
+
- Walks skip `skills/` trees (vendored), `docs/audits/`, `docs/plans/` (records, kept as written). A file named on the command line is always processed. New and edited records get it at commit: § lint-staged names each staged file.
|
|
592
602
|
- Skips tables inside ``` / ~~~ fences and tables already wrapped.
|
|
593
603
|
- A pipe inside an inline-code span is escaped to `\|` only when that restores the separator's column count; an existing `\|` stays literal.
|
|
594
604
|
- Exit 1 on damage it cannot repair, with or without `--check`: `truncated-row` (more cells than the separator; GFM drops the overflow) and `unrendered-table` (header ≠ separator count; GFM renders raw text). A bare pipe in cell prose is indistinguishable from a delimiter → escape it as `\|` by hand.
|
|
@@ -608,3 +618,29 @@ cp .bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs scripts/cleanup/
|
|
|
608
618
|
- Scope: `tmp/` at the top of the checkout the cwd sits in; each worktree prunes its own. `tmp/` itself stays.
|
|
609
619
|
- Age = file mtime. Symlinks never followed: a symlinked `tmp/` is skipped; a symlink inside is removed by its own age, target untouched. A folder goes only when empty and either the sweep emptied it or its own mtime is past the cutoff → a folder another process just made stays.
|
|
610
620
|
- Hand run: `node scripts/cleanup/bkit-tmp-prune.mjs`. Files to keep belong outside `tmp/`.
|
|
621
|
+
|
|
622
|
+
## Disk prune — cleanup steps you own
|
|
623
|
+
|
|
624
|
+
`bkit disk prune` runs only steps you list; bkit deletes nothing. No step file → nothing runs.
|
|
625
|
+
|
|
626
|
+
```bash
|
|
627
|
+
mkdir -p scripts/cleanup ~/.config/bkit
|
|
628
|
+
cp .bkit/templates/scripts/cleanup/bkit-disk-prune.mjs scripts/cleanup/
|
|
629
|
+
cp .bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs ~/.config/bkit/disk-prune.mjs
|
|
630
|
+
```
|
|
631
|
+
|
|
632
|
+
<!-- prettier-ignore -->
|
|
633
|
+
| File | Steps for | Runs from | Committed |
|
|
634
|
+
| --- | --- | --- | --- |
|
|
635
|
+
| `scripts/cleanup/bkit-disk-prune.mjs` | this checkout: build caches, leftover agent worktrees | checkout top, first | yes |
|
|
636
|
+
| `~/.config/bkit/disk-prune.mjs` (`$XDG_CONFIG_HOME/bkit/` when set) | shared tools: Docker, pnpm store, Xcode, Gradle, simulators | home folder | never |
|
|
637
|
+
|
|
638
|
+
- Step list, default-exported: `{ name, mode, run, skip?, paths? }`. `min` = stale, cheap; `max` = all that comes back by itself + every `min` step. `run` / `skip`: shell command or `({ cwd, log, note })` function; `skip` exit 0 or returned reason → skipped. `paths`: what `--dry-run` sizes, the most the step can free.
|
|
639
|
+
- Notes: `note(text)` = found, left for a person. Each sweep replaces its checkout's notes; `bkit tips` prints them first (from a worktree, the main checkout's too), so every workflow close surfaces them. No sweep for 7 days → dropped.
|
|
640
|
+
- Example worktree step: removes a `.worktrees/*` only when nothing is lost — clean, every commit on a remote or at a merged pull request's head (`gh`; squash merges) — via `bkit worktrees remove`, or plain `git worktree remove` when no workflow made it. Branches stay. Keeps a locked one or one committed to in 2 days; notes the rest.
|
|
641
|
+
- Adapt: keep a step only when what it deletes comes back by itself. Left out on purpose: named Docker volumes (local databases), runtimes and SDKs, whole pnpm store (`node_modules` hard-link into it).
|
|
642
|
+
- Wiring: last block of each Husky template — `pre-commit` → `--mode=min --auto`; `pre-push` → `--mode=max --auto`, after every gate (workflow pushes too). Missing → paste at the end of yours.
|
|
643
|
+
- `--auto`: detached, always exit 0. Each mode at most once a day per machine; `max` at most hourly while free disk < `bkit.disk.minFreeGb` (`package.json`, GB, default 40). Log: `~/.cache/bkit/disk-prune.log` (`$XDG_CACHE_HOME/bkit/` when set).
|
|
644
|
+
- Worktrees: `bkit worktrees setup` create / resume under `bkit.disk.minFreeGb` → runs `max` steps, waits. Still under → exit 12, nothing created; stderr lists what `max` steps still cover. No step file → no check.
|
|
645
|
+
- One sweep per machine at a time (`disk-prune.lock` beside the log). Failed step → logged, next runs. CI / cloud → nothing runs.
|
|
646
|
+
- Hand run: `pnpm bkit disk prune --mode=max --dry-run` → each step + its `paths` size; without `--dry-run` → runs now. Exit 1 = a step failed or a step file did not load.
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
{{BKIT_MANAGED_MARKER}}
|
|
4
4
|
|
|
5
5
|
> [!CAUTION]
|
|
6
|
-
> **Purpose:** Reference for inline tracker-block model in `.bkit/core/workflows/bkit-*.md` and `.bkit/core/prompts/bkit-*.md`. **Not consumed by installer** — no `trackers.md` substitution. Per-tracker call bodies (`github` / `linear` / `
|
|
6
|
+
> **Purpose:** Reference for inline tracker-block model in `.bkit/core/workflows/bkit-*.md` and `.bkit/core/prompts/bkit-*.md`. **Not consumed by installer** — no `trackers.md` substitution. Per-tracker call bodies (`github` / `linear` / `jira`, plus `false` for no tracker) live INLINE at each workflow call site; this file documents marker contract, cross-cutting per-tracker conventions, and the issue shapes workflows read (§ Issue shapes).
|
|
7
7
|
>
|
|
8
8
|
> **Rules:**
|
|
9
9
|
>
|
|
@@ -11,18 +11,18 @@
|
|
|
11
11
|
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
12
12
|
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another. Label semantics live in `.bkit/workflows.md` § Tracker Integration; this file is the marker contract + operational per-tracker reference.
|
|
13
13
|
> - Ships to consumers: describe the current setup only. NEVER an internal identifier (tracker issue number, ledger key, review-finding id) and NEVER project history — decisions belong in `docs/decisions.jsonl`, incidents in `docs/knowledge.jsonl`.
|
|
14
|
-
> -
|
|
15
|
-
> - New tracker
|
|
14
|
+
> - Four values: `github`, `linear`, `jira`, `none` (no tracker wired, the default).
|
|
15
|
+
> - New tracker: add enum to `.bkit/core/engine/install/manifest.ts`; document MCP under `mcpServers.<name>` in `.bkit/shared/.mcp.json` and `.bkit/shared/.cursor/mcp.json`; add `<!-- bkit:tracker <name> -->` block after the last tracker block at every call site (extend `GROUP_RE` in `.bkit/core/engine/render/trackers.ts`). No `none` marker — no-tracker content is `false`.
|
|
16
16
|
|
|
17
17
|
## Marker contract
|
|
18
18
|
|
|
19
19
|
Workflow and prompt sources carry wired tracker variants inline. Installer reads `bkit.issueTracker` from consumer manifest, resolves markers when mirroring `.bkit/core/workflows/bkit-*.md` to every host's commands / skills and `.bkit/core/prompts/bkit-*.md` to every host's agents (`.bkit/core/engine/render/trackers.ts`). Mirrors clean — no markers survive.
|
|
20
20
|
|
|
21
|
-
Prompt frontmatter `tools:` lists: every marker must be a YAML comment (` # <!-- bkit:tracker github start -->`) — a bare `<!--` line is invalid YAML; installer strips the `# ` with the marker. A
|
|
21
|
+
Prompt frontmatter `tools:` lists: every marker must be a YAML comment (` # <!-- bkit:tracker github start -->`) — a bare `<!--` line is invalid YAML; installer strips the `# ` with the marker. A group inside the YAML list must end with a `false` block, and every block (incl. `false`) must hold at least one list item — the `none` stub and an empty block both break the YAML. `bkit-utility-update-roadmap` and `bkit-utility-update-tracker` carry `- Bash`, `bkit-audit-generate` `- WebSearch`, in every block for this.
|
|
22
22
|
|
|
23
|
-
### Per-tracker
|
|
23
|
+
### Per-tracker group (`github` / `linear` / `jira`)
|
|
24
24
|
|
|
25
|
-
Every call site = consecutive `github` → `linear`
|
|
25
|
+
Every call site = consecutive `github` → `linear` → `jira` group, optionally trailing `false` block (substantive no-tracker rendering). Without `false`, no-tracker rendering = generic message at resolution time.
|
|
26
26
|
|
|
27
27
|
```text
|
|
28
28
|
<!-- bkit:tracker github start -->
|
|
@@ -31,16 +31,19 @@ mcp__github__… call
|
|
|
31
31
|
<!-- bkit:tracker linear start -->
|
|
32
32
|
mcp__linear__… call
|
|
33
33
|
<!-- bkit:tracker linear end -->
|
|
34
|
+
<!-- bkit:tracker jira start -->
|
|
35
|
+
mcp__jira__… call
|
|
36
|
+
<!-- bkit:tracker jira end -->
|
|
34
37
|
```
|
|
35
38
|
|
|
36
|
-
Resolution:
|
|
39
|
+
Resolution: each tracker → its own block; `none` → group's trailing `false` block if present, else **`_No tracker connected, skip step._`**. List-number prefix (`3. `) before group preserved on kept block / stub. A block outside a full group = orphan; under `jira`, a group with no `jira` block stays whole, so its markers surface as orphans.
|
|
37
40
|
|
|
38
41
|
### Conditional blocks (`bkit:tracker true` / `bkit:tracker false`)
|
|
39
42
|
|
|
40
43
|
Boolean tracker-presence gates for tracker-agnostic content. only no-tracker markers — no `none` marker.
|
|
41
44
|
|
|
42
|
-
- `<!-- bkit:tracker true start/end -->` — kept when tracker connected (`github` or `
|
|
43
|
-
- `<!-- bkit:tracker false start/end -->` — kept only under `none`; removed when wired. Substantive no-tracker behaviour (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`). `false` directly after
|
|
45
|
+
- `<!-- bkit:tracker true start/end -->` — kept when tracker connected (`github`, `linear` or `jira`); **removed entirely under `none`** (no stub). Shared content e.g. comment `{BODY}` fence identical for every tracker.
|
|
46
|
+
- `<!-- bkit:tracker false start/end -->` — kept only under `none`; removed when wired. Substantive no-tracker behaviour (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`). `false` directly after a tracker group = group's `none` rendering; standalone `false` resolved on its own.
|
|
44
47
|
|
|
45
48
|
```text
|
|
46
49
|
<!-- bkit:tracker true start -->
|
|
@@ -48,13 +51,13 @@ Boolean tracker-presence gates for tracker-agnostic content. only no-tracker mar
|
|
|
48
51
|
<!-- bkit:tracker true end -->
|
|
49
52
|
```
|
|
50
53
|
|
|
51
|
-
Conditionals resolved after
|
|
54
|
+
Conditionals resolved after group pass — group nested inside kept `true` resolves first. Removed block consumes leading newline + indentation (no blank gap). Unbalanced `start`/`end` = orphan.
|
|
52
55
|
|
|
53
56
|
**Numbered-step rule:** never wrap numbered list item's NUMBER inside `true` block — under `none` whole item vanishes → numbering gap (`1, 6, 7`). Numbered step with tracker-only body: keep `N.` outside markers; pair `true` body with trailing `false` stub. Put `false` on same line as `true end`, single leading space before stub → inline (`N. _stub_`) not dangling continuation:
|
|
54
57
|
|
|
55
58
|
```text
|
|
56
59
|
N. <!-- bkit:tracker true start -->
|
|
57
|
-
… tracker-only body (
|
|
60
|
+
… tracker-only body (tracker groups allowed inside) …
|
|
58
61
|
<!-- bkit:tracker true end --><!-- bkit:tracker false start --> _No tracker connected, skip step._<!-- bkit:tracker false end -->
|
|
59
62
|
```
|
|
60
63
|
|
|
@@ -62,27 +65,26 @@ Renders `N. <body>` when wired, `N. _No tracker connected, skip step._` under `n
|
|
|
62
65
|
|
|
63
66
|
## Interaction catalog
|
|
64
67
|
|
|
65
|
-
Per-tracker call sites referenced across `.bkit/workflows.md` by these names. Each = inline `github
|
|
68
|
+
Per-tracker call sites referenced across `.bkit/workflows.md` by these names. Each = inline `github` / `linear` / `jira` group; authoritative bodies inline in workflows. `none` column: most sites collapse to generic `_No tracker connected, skip step._`; few carry substantive trailing `false` block (shown) for no-tracker function.
|
|
66
69
|
|
|
67
70
|
<!-- prettier-ignore -->
|
|
68
|
-
| Interaction | Purpose | github | linear | none |
|
|
69
|
-
| --- | --- | --- | --- | --- |
|
|
70
|
-
| `rule-block` | CAUTION-block tracker/labels/comments rules | rules prose | rules prose | "not configured" stub |
|
|
71
|
-
| `issue-id-extraction` | Step 1 `ISSUE_ID` resolution. No match → stop. Never creates an issue | session prompt scan; no match → stop | session prompt scan; no match → stop | scan session prompt; else `ISSUE_ID=""` |
|
|
72
|
-
| `fid-format` | FID slug regex assertion | `^[0-9]+-[a-z0-9-]+$` | `^[a-z]+-[0-9]+-[a-z0-9-]+$` | no strict assert |
|
|
73
|
-
| `issue-read` | Read state + labels + body + comments | `issue_read` `get` / `get_comments` | `get_issue` / `list_comments` | skip (vars empty) |
|
|
74
|
-
| `issue-scan` | Bounded related-issue scan at design/plan/debug entry — writes each hit's body + comments under a `## #{number} — {title} ({state})` heading to a file (advisory, top 10, never gates); broad keyword search in title+body, all states | `search_issues` for ranking only + per-hit `issue_read` `get` / `get_comments` | `list_issues` + per-hit `list_comments` | skip stub (no scan) |
|
|
75
|
-
| `issue-update-phase` | Step 1: set phase label + active state | `issue_write` labels | `save_issue`
|
|
76
|
-
| `issue-update-review` | phase Close hand-off (non-terminal) | no-op (label carries) | `save_issue`
|
|
77
|
-
| `issue-update-failed` | Failure Path additive `bkit:failed` | `issue_write` labels | `save_issue`
|
|
78
|
-
| `issue-update-
|
|
79
|
-
| `issue-update-
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `pr-body-
|
|
85
|
-
| `pr-body-marker` | Literal PR-body marker line | `<!-- bkit:issue=#{ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:issue={ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:fid={FID} -->` |
|
|
71
|
+
| Interaction | Purpose | github | linear | jira | none |
|
|
72
|
+
| --- | --- | --- | --- | --- | --- |
|
|
73
|
+
| `rule-block` | CAUTION-block tracker/labels/comments rules | rules prose | rules prose | rules prose | "not configured" stub |
|
|
74
|
+
| `issue-id-extraction` | Step 1 `ISSUE_ID` resolution. No match → stop. Never creates an issue | session prompt scan; no match → stop | session prompt scan; no match → stop | session prompt scan (incl. `/browse/{KEY}` links); no match → stop | scan session prompt; else `ISSUE_ID=""` |
|
|
75
|
+
| `fid-format` | FID slug regex assertion | `^[0-9]+-[a-z0-9-]+$` | `^[a-z]+-[0-9]+-[a-z0-9-]+$` | `^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$` | no strict assert |
|
|
76
|
+
| `issue-read` | Read state + labels + body + comments | `issue_read` `get` / `get_comments` | `get_issue` / `list_comments` | `getJiraIssue` `view: "evidence"` / `executeRead` `listJiraIssueComments` | skip (vars empty) |
|
|
77
|
+
| `issue-scan` | Bounded related-issue scan at design/plan/debug entry — writes each hit's body + comments under a `## #{number} — {title} ({state})` heading to a file (advisory, top 10, never gates); broad keyword search in title+body, all states | `search_issues` for ranking only + per-hit `issue_read` `get` / `get_comments` | `list_issues` + per-hit `list_comments` | `searchJiraIssuesUsingJql` (`text ~` per keyword, inside `bkit.jira.project`) + per-hit `listJiraIssueComments` | skip stub (no scan) |
|
|
78
|
+
| `issue-update-phase` | Step 1: set phase label (`bkit:debug` included; drops `next:*`, `bkit:failed`) + active state | `issue_write` labels | `save_issue_label` per new label, then `save_issue` labels, then `save_issue` state `bkit.linear.progress` | `editJiraIssue` full label set, then transition to `bkit.jira.progress` | skip |
|
|
79
|
+
| `issue-update-review` | phase Close hand-off (non-terminal) | no-op (label carries) | `save_issue` state `bkit.linear.review` | transition to `bkit.jira.review` | skip |
|
|
80
|
+
| `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.linear.review` | `editJiraIssue` full label set, then transition to `bkit.jira.review` | skip |
|
|
81
|
+
| `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.linear.review` | `editJiraIssue` full label set, then transition to `bkit.jira.review` | skip |
|
|
82
|
+
| `issue-update-status` | Projects v2 board status (best-effort) | `projects_write` add/update item | no-op (state carries) | no-op (status carries) | skip |
|
|
83
|
+
| `comment-post-step` | new comment per workflow step | `add_issue_comment` | `save_comment` | `addOrEditJiraIssueComment` | skip |
|
|
84
|
+
| `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 |
|
|
85
|
+
| `kill-switch-check` | Terminate if `bkit:auto` absent | label check | label check | label check | inactive |
|
|
86
|
+
| `pr-body-metadata` | Parse PR-body issue/FID marker | `pull_request_read` + parse | same (GitHub PR) | same (GitHub PR) | FID-only, no fail-closed |
|
|
87
|
+
| `pr-body-marker` | Literal PR-body marker line | `<!-- bkit:issue=#{ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:issue={ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:issue={ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:fid={FID} -->` |
|
|
86
88
|
|
|
87
89
|
Phase-label set + additive-label semantics: `.bkit/workflows.md` § Tracker Integration.
|
|
88
90
|
|
|
@@ -94,7 +96,7 @@ Workflows read issue body + comments (`bkit issues text`), never title (title
|
|
|
94
96
|
| Shape | When | Next command | Sections (**required**) |
|
|
95
97
|
| --- | --- | --- | --- |
|
|
96
98
|
| idea | how it should work still open | `/bkit-design #N` | **Problem**, **Outcome**, Success criteria, Constraints and non-goals, Decisions already made, Open questions, References |
|
|
97
|
-
| change | what to build + how to tell done both known | `/bkit-plan #N`; or `/bkit-build #N` / `lite
|
|
99
|
+
| change | what to build + how to tell done both known | `/bkit-plan #N`; or `/bkit-build #N` / `build:lite` straight from issue | **Narrative**, **Success Criteria**, Edge Cases, **Derived Test Matrix**, **Tasks**, Open Questions & Assumptions, Breaking Changes & Naming, Out of Scope, References |
|
|
98
100
|
| bug | worked / should work, does not | test or CI run already fails → `/bkit-debug #N` on branch fix lands on (`[soak]` if intermittent); nothing fails → `/bkit-debug #N [repro]` (failing test first; `[soak]` too if intermittent) | **Failing test or CI run** (`none yet` allowed), **What happened**, **What should happen**, **Steps to reproduce**, How often, Affected area, Where and when, Evidence, References |
|
|
99
101
|
|
|
100
102
|
**Change shape syntax** (plan keeps it, `docs/templates/bkit-plan.md` § Spec):
|
|
@@ -108,34 +110,86 @@ Workflows read issue body + comments (`bkit issues text`), never title (title
|
|
|
108
110
|
- [ ] **Task N:** {change}. **Done when:** {verifiable check}. **Test first:** `{test file}` `{test name}` fails on {assertion}.
|
|
109
111
|
```
|
|
110
112
|
|
|
111
|
-
- `/bkit-build` with no plan builds these Tasks: each `Test first` test must fail before its code (`tests green --brief=`); missing `Done when` not a FAIL. `lite
|
|
113
|
+
- `/bkit-build` with no plan builds these Tasks: each `Test first` test must fail before its code (`tests green --brief=`); missing `Done when` not a FAIL. `build:lite` checks neither. Nothing ticks issue boxes.
|
|
112
114
|
|
|
113
115
|
**Machine-read lines** — exact syntax, anywhere in body; nothing else in References is fetched:
|
|
114
116
|
|
|
115
117
|
<!-- prettier-ignore -->
|
|
116
118
|
| Line | Read by | Effect |
|
|
117
119
|
| --- | --- | --- |
|
|
118
|
-
| `**Parent design:** [{FID}-design.md](docs/plans/{YYYYMM}/{FID}-design.md)` | plan Step 1 | sets `PARENT_FID` → design = spec source; absent → the design made on the same issue (`bkit fids design`) |
|
|
120
|
+
| `**Parent design:** [{FID}-design.md](https://github.com/{OWNER_REPO}/blob/dev/docs/plans/{YYYYMM}/{FID}-design.md)` | plan Step 1 | sets `PARENT_FID` → design = spec source; absent → the design made on the same issue (`bkit fids design`) |
|
|
119
121
|
| `**Audit reports:** docs/audits/{YYYYMM}/{slug}.md (findings {ids})` | plan Step 1 | each path → `AUDIT_PATHS`; path not a file → Failure Path |
|
|
120
|
-
| `###### bkit:blocked-by start` · `- #{N}` per line · `###### bkit:blocked-by end` | build `issue-blockers-check` (github; linear → native relations) | any listed issue open → build stops |
|
|
122
|
+
| `###### bkit:blocked-by start` · `- #{N}` per line · `###### bkit:blocked-by end` | build `issue-blockers-check` (github; linear / jira → native relations) | any listed issue open → build stops |
|
|
121
123
|
| `###### bkit:ignore-earlier` | `bkit issues text` | drops all earlier content; human-placed only |
|
|
122
124
|
| `###### bkit:generated` (comment first line) | `bkit issues text` | comment dropped from input |
|
|
123
125
|
|
|
124
|
-
**References** — exact strings agents can search: issue `#N — {title}` (linear `
|
|
126
|
+
**References** — exact strings agents can search: issue `#N — {title}` (linear / jira `KEY-N — {title}`); doc `{path} § {section}`; ledger row `docs/{ledger}.jsonl` key `` `{key}` ``. Labels: type label (github `enhancement` / `bug`; linear the team's own, default `Improvement` / `Feature` / `Bug`; jira none — issue type carries type) + one `next:*` (`.agents/rules.md` § Tracker next labels); never phase or `bkit:*` labels — workflows set them (`.bkit/workflows.md` § Tracker Integration).
|
|
125
127
|
|
|
126
128
|
**Drafting from bkit output** (suggest only; file after human confirmation):
|
|
127
129
|
|
|
128
130
|
<!-- prettier-ignore -->
|
|
129
131
|
| Source | Shape | Carry |
|
|
130
132
|
| --- | --- | --- |
|
|
131
|
-
| audit
|
|
132
|
-
|
|
|
133
|
+
| audit run, tracker wired, no open audit parent for its template (`Parent: missing`) | audit parent (below) | template path line |
|
|
134
|
+
| audit `Suggested Issues` row | by `Next Step`: `/bkit-design` → idea; `/bkit-plan`, `/bkit-build`, `build:lite` → change; `/bkit-debug`, `debug:lite` → bug; `manual` → plain task | `**Audit reports:**` line with row's finding IDs; sub-issue of the template's audit parent (linear → `parentId`; jira → `parent`) |
|
|
135
|
+
| design `Suggested Workstreams` (2+; design summary asks) | title = workstream name; body = its scope, spec left to design; filed in `Requires` order | `**Parent design:**` line; blocked-by block = issues filed for its `Requires` (linear → `blockedBy` relation; jira → `Blocks` link, `inwardIssue` = blocker) |
|
|
133
136
|
| roadmap item with no issue (ledger row, audit candidate) | by recommended command, as audit row | ledger `key` / report path in References |
|
|
134
137
|
|
|
138
|
+
**Audit parent** — one standing issue per audit template, shared by every run of that template; never one per run, never one across templates.
|
|
139
|
+
|
|
140
|
+
<!-- prettier-ignore -->
|
|
141
|
+
| Field | Value |
|
|
142
|
+
| --- | --- |
|
|
143
|
+
| Title | template H1 (`Security Audit`) |
|
|
144
|
+
| Body | names `docs/templates/bkit-audit-{slug}.md` verbatim (`@bkit-audit-generate` finds the parent by this path); run line `@bkit-audit-generate docs/templates/bkit-audit-{slug}.md #{N}` (linear / jira `KEY-N`); report path `docs/audits/{YYYYMM}/{slug}.md` |
|
|
145
|
+
| Labels | project's own (e.g. `maintenance`); no workflow, `next:*` or `bkit:*` label — it runs no workflow |
|
|
146
|
+
| Milestone | one milestone holding every audit parent, when the project keeps one |
|
|
147
|
+
| State | stays open; runs never close it; filed issues reference it as `#N — {title}`, never `Closes #N` |
|
|
148
|
+
| Children | every issue filed from its runs' `Suggested Issues`, always (github sub-issues; linear `parentId`; jira `parent`) |
|
|
149
|
+
| Comments | one `### Audit Summary: {slug}` comment per run — posted by the run when named or found; a newly filed parent gets the run's saved `parent-comment.md` as its first comment |
|
|
150
|
+
|
|
135
151
|
## github — Projects v2 board (optional)
|
|
136
152
|
|
|
137
153
|
`issue-update-status` reads `package.json` `bkit.githubProject` = `{ owner (org login), number, statusFieldId, progressOptionId, reviewOptionId, doneOptionId }` (non-secret, committed). Absent → board sync skipped (best-effort, never gates). Discover ids once: `gh api /orgs/{owner}/projectsV2/{number}/fields --jq '.[] | select(.name=="Status")'` (Status field numeric `id` → `statusFieldId`; each option raw `id` → option id, e.g. `47fc9ee4`; `PVTSSF_…` node id from `gh project field-list` is not field id — `projects_write` rejects it). Requires `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) + `BKIT_GH_TOKEN` org Projects R/W. Org-owned boards only — fine-grained PATs cannot reach user-owned projects, nor span orgs; use a classic PAT with `project` when the token must cover more than one owner. `value` = single-select **option id**, not option name. Failure → retry once after 5s, then continue. `doneOptionId` is **reserved and never written** — ship terminal sets `reviewOptionId`, and a human moves the item to Done on acceptance (§ `issue-update-merged` in `.bkit/workflows.md`).
|
|
138
154
|
|
|
139
155
|
## linear — notes
|
|
140
156
|
|
|
141
|
-
Linear `ISSUE_ID`s carry team prefix (e.g. `TEAM-123`) — FID inherits (`team-123-slug`). GitHub FIDs numeric-only (`123-slug`). Cross-provider scripts must tolerate both shapes. `
|
|
157
|
+
Linear `ISSUE_ID`s carry team prefix (e.g. `TEAM-123`) — FID inherits (`team-123-slug`). GitHub FIDs numeric-only (`123-slug`). Cross-provider scripts must tolerate both shapes. `bkit repo info` prints `trackerTeam` / `trackerProject` from `package.json` `bkit.linear.team` / `bkit.linear.project` (null → related search unscoped). No separate project board — issue state carries status → `issue-update-status` no-op.
|
|
158
|
+
|
|
159
|
+
Linear `save_issue` is all-or-nothing: one state or label name the team lacks rejects the whole call, valid fields included, and Linear never creates the missing name. A default team has states Backlog / Todo / In Progress / Done / Canceled / Duplicate and labels Improvement / Feature / Bug. Workflows therefore write labels and state in separate calls, labels first. Each label the transition adds (`add` from `bkit issues labels` / `bkit workflows fail`) is created first with `save_issue_label({ name })`, a workspace label; `already exists` = done. Phase start sets state `bkit.linear.progress` (default `started`, a state type every team has). Hand-off, Failure Path and ship terminal set state `bkit.linear.review` (default `In Review`); on a team without it the state call fails alone, is logged `Unapplied`, and the issue keeps its started state while `bkit:merged` / `bkit:failed` carry the hand-off. Label names resolve case-insensitively.
|
|
160
|
+
|
|
161
|
+
## jira — setup and notes
|
|
162
|
+
|
|
163
|
+
Jira Cloud only. `ISSUE_ID` = issue key (`PROJ-123`) → FID `proj-123-slug`. MCP server `jira` = Atlassian Rovo MCP `https://mcp.atlassian.com/v2/mcp`, header `Authorization: Bearer ${BKIT_JIRA_API_TOKEN}`. Workflows run locally; no Jira-side trigger starts cloud runs.
|
|
164
|
+
|
|
165
|
+
<!-- prettier-ignore -->
|
|
166
|
+
| `package.json` `bkit.jira` key | Value |
|
|
167
|
+
| --- | --- |
|
|
168
|
+
| `site` | `https://<site>.atlassian.net` — every call's `cloudId`; bare `<site>` rejected |
|
|
169
|
+
| `project` | project key (`PROJ`); scopes related search + `bkit-utility-update-tracker`; absent → unscoped |
|
|
170
|
+
| `progress` | status phase start moves to; default `In Progress` |
|
|
171
|
+
| `review` | status hand-off, Failure Path and ship terminal move to; default `In Review` |
|
|
172
|
+
|
|
173
|
+
**Setup** (once):
|
|
174
|
+
|
|
175
|
+
1. Org admin: https://admin.atlassian.com → org owning `<site>.atlassian.net` → **Rovo** → **Rovo MCP server** (or admin search `mcp`) → **Authentication** → **Allow API token authentication** on; **Permissions**: **Read**, **Write**, **Search** allowed (no **Delete** / **Manage** needed). **Connectors** is the wrong page; **Domains** applies to OAuth only.
|
|
176
|
+
2. Each person: 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**) → Jira read / write / search scopes (`read:jira:agent-interface`, `write:jira:agent-interface`, `search:jira:agent-interface`) → copy token (shown once) → `BKIT_JIRA_API_TOKEN` in `.bkit/.env` → `direnv allow`. Token works on MCP only; Jira REST API answers 401.
|
|
177
|
+
3. `bkit install --tracker=jira`; set `bkit.jira.site` + `bkit.jira.project`. Claude Code: approve project `.mcp.json` once in an interactive `claude` session (`claude mcp list` shows "Pending approval" until then).
|
|
178
|
+
|
|
179
|
+
**Behaviour workflows rely on:**
|
|
180
|
+
|
|
181
|
+
- Status changes only by transition: workflows list the issue's transitions (`executeRead` `listJiraIssueTransitions`) and fire the one whose `to.name` = target status; none → `Unapplied`, labels still land. Basic team-managed boards may lack `In Review` → set `bkit.jira.review` to a status the board has.
|
|
182
|
+
- Labels: `getJiraIssue` returns them only with `view: "evidence"` (or `"full"`); `editJiraIssue` replaces the whole set; Jira creates a label on first use; storage case-sensitive, JQL search not.
|
|
183
|
+
- Comments: posted as markdown, stored as Atlassian Document Format, read back as markdown with same meaning, not same bytes (`-` bullets → `*`, `*em*` → `_em_`, extra blank lines; checkboxes and `> [!NOTE]` alerts come back escaped). One comment Jira cannot express in markdown (mention, image, panel) turns its whole page HTML (`appliedContentFormat: "html"`) → workflows re-read that page one comment per call. Max 32,767 characters → workflows split at line breaks.
|
|
184
|
+
- Blockers: native `Blocks` link; `createJiraIssueLink` reads backwards — `inwardIssue` = blocker, `outwardIssue` = blocked.
|
|
185
|
+
- No type labels: the issue type (Bug / Task / Story) carries type.
|
|
186
|
+
|
|
187
|
+
<!-- prettier-ignore -->
|
|
188
|
+
| Symptom | Fix |
|
|
189
|
+
| --- | --- |
|
|
190
|
+
| Only 4 tools listed (`getTeamworkGraphContext` …), no Jira tools | URL `/v2/mcp`, not `/v1/mcp` |
|
|
191
|
+
| Every call: `Cloud id: … isn't explicitly granted by the user` | Scoped **Atlassian MCP V2** token sent as `Bearer`, not classic token or `Basic` |
|
|
192
|
+
| `missing the scope claim` | Classic token → create token with scopes |
|
|
193
|
+
| `Failed to fetch cloud ID for: <site>` | `bkit.jira.site` = full `https://<site>.atlassian.net` |
|
|
194
|
+
| `Request must be an initialize request if no session ID is provided` (scripted call) | `initialize` first, then send `Mcp-Session-Id` |
|
|
195
|
+
| HTTP 403 Cloudflare 1010 (scripted call) | Send a non-default `User-Agent` |
|