@cbartens/bkit 5.5.0 → 6.0.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 +30 -20
- package/.bkit/core/.agents/docs.md +1 -0
- package/.bkit/core/.agents/rules.md +51 -26
- package/.bkit/core/.bkit/README.md +29 -19
- package/.bkit/core/.bkit/authoring.md +117 -0
- package/.bkit/core/.bkit/cloud.md +11 -11
- package/.bkit/core/.bkit/comparison.md +5 -5
- package/.bkit/core/.bkit/install.md +20 -20
- package/.bkit/core/.bkit/jsonl.md +202 -122
- package/.bkit/core/.bkit/lite.md +1 -1
- package/.bkit/core/.bkit/pipeline.md +49 -52
- package/.bkit/core/.bkit/prompts.md +106 -167
- package/.bkit/core/.bkit/providers.md +29 -32
- package/.bkit/core/.bkit/templates.md +44 -18
- package/.bkit/core/.bkit/trackers.md +60 -28
- package/.bkit/core/.bkit/workflows.md +399 -359
- package/.bkit/core/AGENTS.md +16 -22
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
- package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
- package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
- package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
- package/.bkit/core/docs/templates/bkit-plan.md +97 -226
- package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
- package/.bkit/core/engine/checks/after/github.ts +101 -72
- package/.bkit/core/engine/checks/after/index.ts +10 -12
- package/.bkit/core/engine/checks/after/suppression.ts +8 -5
- package/.bkit/core/engine/checks/after/tools.ts +47 -92
- package/.bkit/core/engine/checks/before/env.ts +2 -2
- package/.bkit/core/engine/checks/before/files.ts +5 -4
- package/.bkit/core/engine/checks/before/index.ts +18 -1
- package/.bkit/core/engine/checks/before/repo.ts +168 -2
- package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
- package/.bkit/core/engine/checks/tips/detect.ts +34 -0
- package/.bkit/core/engine/checks/tips/index.ts +10 -7
- package/.bkit/core/engine/cli.ts +20 -53
- package/.bkit/core/engine/commands/analysis.ts +171 -140
- package/.bkit/core/engine/commands/ci/ci.ts +6 -6
- package/.bkit/core/engine/commands/comply.ts +77 -103
- package/.bkit/core/engine/commands/install/doctor.ts +2 -2
- package/.bkit/core/engine/commands/install/install.ts +57 -18
- package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
- package/.bkit/core/engine/commands/land.ts +18 -12
- package/.bkit/core/engine/commands/lib.ts +79 -17
- package/.bkit/core/engine/commands/registry.ts +4 -0
- package/.bkit/core/engine/commands/setup/setup.ts +7 -7
- package/.bkit/core/engine/commands/stats.ts +204 -0
- package/.bkit/core/engine/commands/tips.ts +10 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
- package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
- package/.bkit/core/engine/commands/workflow/context.ts +853 -29
- package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
- package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
- package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
- package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
- package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
- package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
- package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
- package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
- package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
- package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
- package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
- package/.bkit/core/engine/commands/workflow/status.ts +142 -29
- package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
- package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
- package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
- package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
- package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
- package/.bkit/core/engine/install/manifest.ts +11 -9
- package/.bkit/core/engine/install/modules/cloud.ts +21 -13
- package/.bkit/core/engine/install/modules/core.ts +325 -7
- package/.bkit/core/engine/install/modules/opencode.ts +2 -2
- package/.bkit/core/engine/install/version-file.ts +6 -2
- package/.bkit/core/engine/ledgers/migrate.ts +92 -0
- package/.bkit/core/engine/ledgers/status.ts +92 -15
- package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
- package/.bkit/core/engine/render/hosts.ts +4 -0
- package/.bkit/core/engine/render/models.ts +12 -0
- package/.bkit/core/engine/shared/branches.ts +4 -1
- package/.bkit/core/engine/shared/egress.ts +7 -0
- package/.bkit/core/engine/shared/json.ts +25 -7
- package/.bkit/core/engine/shared/settings.ts +202 -33
- package/.bkit/core/engine/shared/text.ts +361 -0
- package/.bkit/core/engine/tools/grammar-density.ts +215 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
- package/.bkit/core/engine/tools/instructions.ts +1751 -0
- package/.bkit/core/hooks/gateguard-engine.js +24 -23
- package/.bkit/core/hooks/guardrails-shell.js +2 -3
- package/.bkit/core/hooks/guardrails-tiers.js +7 -1
- package/.bkit/core/hooks/readguard-engine.js +2 -2
- package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
- package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
- package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
- package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
- package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
- package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
- package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
- package/.bkit/core/prompts/bkit-design-generate.md +33 -13
- package/.bkit/core/prompts/bkit-design-organise.md +25 -12
- package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
- package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
- package/.bkit/core/prompts/bkit-design-spike.md +30 -13
- package/.bkit/core/prompts/bkit-design-update.md +33 -19
- package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
- package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
- package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
- package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
- package/.bkit/core/prompts/bkit-plan-update.md +61 -24
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
- package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
- package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
- package/.bkit/core/workflows/bkit-auto.md +54 -46
- package/.bkit/core/workflows/bkit-build.md +577 -458
- package/.bkit/core/workflows/bkit-debug.md +348 -333
- package/.bkit/core/workflows/bkit-design.md +201 -237
- package/.bkit/core/workflows/bkit-plan.md +210 -321
- package/.bkit/core/workflows/bkit-ship.md +328 -278
- package/.bkit/shared/.bkit/.env.example +2 -2
- package/.bkit/shared/.claude/settings.json +11 -0
- package/.bkit/shared/.cursor/mcp.json +1 -1
- package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
- package/.bkit/shared/.gitattributes +1 -1
- package/.bkit/shared/.mcp.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -0
- package/.bkit/shared/CLAUDE.md +2 -2
- package/.bkit/shared/GEMINI.md +2 -2
- package/.bkit/shared/docs/architecture.md +1 -1
- package/.bkit/shared/docs/data-schema.md +1 -1
- package/.bkit/shared/docs/deployments.md +16 -28
- package/.bkit/shared/docs/design.md +1 -1
- package/.bkit/shared/docs/noise.md +1 -1
- package/.bkit/shared/docs/observability.md +2 -2
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/setup.md +1 -1
- package/.bkit/shared/docs/technology.md +1 -1
- package/.bkit/shared/docs/testing.md +27 -10
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
- package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
- package/.bkit/templates/.husky/pre-push +52 -13
- package/.bkit/templates/.prettierignore +7 -0
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
- package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
- package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
- package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
- package/CHANGELOG.md +142 -0
- package/README.md +58 -34
- package/dist/checks/after/ci-yml.js +39 -29
- package/dist/checks/after/github.js +99 -72
- package/dist/checks/after/index.js +11 -13
- package/dist/checks/after/suppression.js +8 -5
- package/dist/checks/after/tools.js +40 -83
- package/dist/checks/before/env.js +2 -2
- package/dist/checks/before/files.js +5 -3
- package/dist/checks/before/index.js +15 -2
- package/dist/checks/before/repo.js +163 -2
- package/dist/checks/tips/catalogue.js +14 -5
- package/dist/checks/tips/detect.js +32 -0
- package/dist/checks/tips/index.js +7 -5
- package/dist/cli.js +19 -47
- package/dist/commands/analysis.js +109 -100
- package/dist/commands/ci/ci.js +6 -6
- package/dist/commands/comply.js +54 -91
- package/dist/commands/install/doctor.js +2 -2
- package/dist/commands/install/install.js +50 -19
- package/dist/commands/install/uninstall.js +59 -28
- package/dist/commands/land.js +16 -12
- package/dist/commands/lib.js +51 -16
- package/dist/commands/registry.js +4 -0
- package/dist/commands/setup/setup.js +7 -7
- package/dist/commands/stats.js +136 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +656 -56
- package/dist/commands/workflow/challenge.js +556 -0
- package/dist/commands/workflow/context.js +709 -30
- package/dist/commands/workflow/counters.js +208 -75
- package/dist/commands/workflow/decisions.js +441 -0
- package/dist/commands/workflow/disk.js +2 -2
- package/dist/commands/workflow/fids.js +689 -33
- package/dist/commands/workflow/issues.js +362 -99
- package/dist/commands/workflow/ledgers.js +762 -27
- package/dist/commands/workflow/locks.js +24 -2
- package/dist/commands/workflow/plan-blocks.js +437 -0
- package/dist/commands/workflow/plan-versions.js +22 -0
- package/dist/commands/workflow/prs.js +142 -32
- package/dist/commands/workflow/repo.js +52 -7
- package/dist/commands/workflow/roadmap.js +9 -7
- package/dist/commands/workflow/run-facts.js +426 -0
- package/dist/commands/workflow/runs.js +144 -43
- package/dist/commands/workflow/runtime.js +12 -1
- package/dist/commands/workflow/status.js +130 -29
- package/dist/commands/workflow/step-table.js +276 -0
- package/dist/commands/workflow/steps.js +171 -80
- package/dist/commands/workflow/summary.js +275 -0
- package/dist/commands/workflow/tests.js +834 -136
- package/dist/commands/workflow/tracker.js +983 -0
- package/dist/commands/workflow/workflows.js +834 -195
- package/dist/commands/workflow/workstreams.js +11 -5
- package/dist/commands/workflow/worktrees.js +221 -22
- package/dist/install/manifest.js +11 -9
- package/dist/install/modules/cloud.js +22 -13
- package/dist/install/modules/core.js +326 -7
- package/dist/install/modules/opencode.js +2 -2
- package/dist/install/version-file.js +6 -2
- package/dist/ledgers/migrate.js +81 -0
- package/dist/ledgers/status.js +61 -8
- package/dist/ledgers/telemetry.js +905 -124
- package/dist/render/hosts.js +4 -0
- package/dist/render/models.js +12 -0
- package/dist/shared/branches.js +3 -1
- package/dist/shared/egress.js +7 -0
- package/dist/shared/json.js +20 -7
- package/dist/shared/settings.js +147 -26
- package/dist/shared/text.js +333 -0
- package/dist/tools/grammar-density.js +183 -0
- package/dist/tools/instructions-sources.js +721 -0
- package/dist/tools/instructions.js +1579 -0
- package/package.json +114 -23
- package/.bkit/core/engine/commands/harvest.ts +0 -459
- package/.bkit/core/engine/tools/wording.ts +0 -748
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
- package/.bkit/core/prompts/bkit-build-summary.md +0 -94
- package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
- package/.bkit/core/prompts/bkit-design-summary.md +0 -107
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
- package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
- package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
- package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
- package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
- package/dist/commands/harvest.js +0 -353
- package/dist/tools/wording.js +0 -680
|
@@ -71,13 +71,13 @@ BKIT_GH_TOKEN=
|
|
|
71
71
|
# Generate at: https://linear.app/settings/api
|
|
72
72
|
BKIT_LINEAR_API_KEY=
|
|
73
73
|
|
|
74
|
-
#
|
|
74
|
+
# BKIT_JIRA_API_KEY — Atlassian API token for the Jira MCP server
|
|
75
75
|
# (mcp.atlassian.com/v2/mcp), sent as `Authorization: Bearer`. Create it with
|
|
76
76
|
# "Create API token with scopes" and pick the app "Atlassian MCP V2"; a classic
|
|
77
77
|
# token or another app is refused. An org admin must first allow API-token sign-in
|
|
78
78
|
# for the Rovo MCP server. Steps: .bkit/trackers.md § jira.
|
|
79
79
|
# Generate at: https://id.atlassian.com/manage-profile/security/api-tokens
|
|
80
|
-
|
|
80
|
+
BKIT_JIRA_API_KEY=
|
|
81
81
|
|
|
82
82
|
# BKIT_ANTHROPIC_API_KEY — Anthropic API key. Only needed if you run Claude Code
|
|
83
83
|
# without a Claude subscription (pay-per-token mode). Subscription users leave
|
|
@@ -16,6 +16,17 @@
|
|
|
16
16
|
"Bash(rm -rf /*)",
|
|
17
17
|
"Bash(rm -rf ~/*)",
|
|
18
18
|
"Bash(rm -rf $HOME/*)",
|
|
19
|
+
"Bash(rm -rf ~)",
|
|
20
|
+
"Bash(rm -rf $HOME)",
|
|
21
|
+
"Bash(rm -rf ${HOME})",
|
|
22
|
+
"Bash(rm -rf ${HOME}/*)",
|
|
23
|
+
"Bash(rm -fr /*)",
|
|
24
|
+
"Bash(rm -fr ~)",
|
|
25
|
+
"Bash(rm -fr ~/*)",
|
|
26
|
+
"Bash(rm -fr $HOME)",
|
|
27
|
+
"Bash(rm -fr $HOME/*)",
|
|
28
|
+
"Bash(rm -fr ${HOME})",
|
|
29
|
+
"Bash(rm -fr ${HOME}/*)",
|
|
19
30
|
"Bash(chmod -R 777 /:*)",
|
|
20
31
|
"Bash(git push --force)",
|
|
21
32
|
"Bash(git push --force *)",
|
|
@@ -23,7 +23,7 @@ docs/roadmap.md merge=union
|
|
|
23
23
|
.bkit/stats.jsonl merge=union
|
|
24
24
|
|
|
25
25
|
# `.bkit/friction.jsonl` is deliberately absent: it is the one ledger rows are
|
|
26
|
-
# REMOVED from (
|
|
26
|
+
# REMOVED from (bkit's harvest drains it). Union would resurrect rows a drain
|
|
27
27
|
# deleted, so a conflict there carries real information and must stay blocking.
|
|
28
28
|
|
|
29
29
|
# Append-only NDJSON workflow status logs: union auto-concatenates both branches'
|
package/.bkit/shared/.mcp.json
CHANGED
|
@@ -53,6 +53,17 @@
|
|
|
53
53
|
"rm -rf /*": "deny",
|
|
54
54
|
"rm -rf ~/*": "deny",
|
|
55
55
|
"rm -rf $HOME/*": "deny",
|
|
56
|
+
"rm -rf ~": "deny",
|
|
57
|
+
"rm -rf $HOME": "deny",
|
|
58
|
+
"rm -rf ${HOME}": "deny",
|
|
59
|
+
"rm -rf ${HOME}/*": "deny",
|
|
60
|
+
"rm -fr /*": "deny",
|
|
61
|
+
"rm -fr ~": "deny",
|
|
62
|
+
"rm -fr ~/*": "deny",
|
|
63
|
+
"rm -fr $HOME": "deny",
|
|
64
|
+
"rm -fr $HOME/*": "deny",
|
|
65
|
+
"rm -fr ${HOME}": "deny",
|
|
66
|
+
"rm -fr ${HOME}/*": "deny",
|
|
56
67
|
"git push --force*": "deny",
|
|
57
68
|
"git push -f*": "deny",
|
|
58
69
|
"git push --force-with-lease*": "allow",
|
package/.bkit/shared/CLAUDE.md
CHANGED
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
{{BKIT_MANAGED_MARKER}}
|
|
6
6
|
|
|
7
|
-
- **Rules:** Read `.agents/rules.md` →
|
|
7
|
+
- **Rules file:** Read `.agents/rules.md` → follow all rules.
|
|
8
8
|
|
|
9
|
-
**Memory hygiene:** Claude Code auto-memories (`MEMORY.md` + `memory/*.md`) are
|
|
9
|
+
**Memory hygiene:** Claude Code auto-memories (`MEMORY.md` + `memory/*.md`) are pointers, never copies. Facts in `docs/*.md`, `.agents/rules.md`, or `CLAUDE.md` → ONLY save path, section, and one-line hook. Issue states → query tracker or `docs/roadmap.md`; NEVER snapshot into memory.
|
|
10
10
|
|
|
11
11
|
<!-- bkit:end -->
|
package/.bkit/shared/GEMINI.md
CHANGED
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
|
|
5
5
|
{{BKIT_MANAGED_MARKER}}
|
|
6
6
|
|
|
7
|
-
- **Rules:** Read `.agents/rules.md` →
|
|
7
|
+
- **Rules file:** Read `.agents/rules.md` → follow all rules.
|
|
8
8
|
|
|
9
|
-
**Memory hygiene:** durable facts live in `docs/*.md`, `.agents/rules.md`, or this file — Antigravity loads `GEMINI.md` as a workspace rule, so keep it a pointer, never a copy. Issue states → query
|
|
9
|
+
**Memory hygiene:** durable facts live in `docs/*.md`, `.agents/rules.md`, or this file — Antigravity loads `GEMINI.md` as a workspace rule, so keep it a pointer, never a copy. Issue states → query tracker or `docs/roadmap.md`; NEVER snapshot them here.
|
|
10
10
|
|
|
11
11
|
<!-- bkit:end -->
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
> **Rules:**
|
|
11
11
|
>
|
|
12
12
|
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
13
|
-
> - Notation: one job per mark — `.bkit/
|
|
13
|
+
> - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
|
|
14
14
|
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
15
15
|
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
|
|
16
16
|
> - Topology / boundaries only; operational rules and library lists → domain docs.
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
> **Rules:**
|
|
11
11
|
>
|
|
12
12
|
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
13
|
-
> - Notation: one job per mark — `.bkit/
|
|
13
|
+
> - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
|
|
14
14
|
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
15
15
|
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
|
|
16
16
|
> - One section / table: `Field | Type | Unique | Notes`, `Indices`, `Pending`.
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
> **Rules:**
|
|
11
11
|
>
|
|
12
12
|
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
13
|
-
> - Notation: one job per mark — `.bkit/
|
|
13
|
+
> - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
|
|
14
14
|
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
15
15
|
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
|
|
16
16
|
> - Pre-push runs project gate set locally (see "Pre-push checklist" below); never `--no-verify`.
|
|
@@ -117,8 +117,8 @@ Bkit `bkit-ci.yml` recognises tags below. Case-sensitive, literal `[...]` form;
|
|
|
117
117
|
<!-- prettier-ignore -->
|
|
118
118
|
| Tag | Effect | Scope |
|
|
119
119
|
| --- | --- | --- |
|
|
120
|
-
| `[force cache]` | Busts the task-runner cache for the run — recompute instead of replaying cache hits (e.g. turbo: `TURBO_FORCE=1`).
|
|
121
|
-
| `[force build]` | The lighter hammer. Exposes `should_force_build=true` + `run_level=full`; does **not** bypass `web_affected`, so no integration / e2e / @live unless web is genuinely affected. Rebuild without paying @live's side effects.
|
|
120
|
+
| `[force cache]` | Busts the task-runner cache for the run — recompute instead of replaying cache hits (e.g. turbo: `TURBO_FORCE=1`). Use when investigating suspected ghost-greens. | Read by `Detect Direct Push` |
|
|
121
|
+
| `[force build]` | The lighter hammer. Exposes `should_force_build=true` + `run_level=full`; does **not** bypass `web_affected`, so no integration / e2e / @live unless web is genuinely affected. Rebuild without paying @live's side effects. Deploy steps act on it only when they gate on the output. | Read by `Detect Direct Push` |
|
|
122
122
|
| `[force full]` | The hammer. `run_level=full` **and** it bypasses `web_affected`, so integration, `bkit-tests-e2e-web`, and `bkit-tests-live-web` run on any commit, including docs-only. The E2E spec set does not change, because a PR already runs the full suite. `@live` stays **push-only** (a docs-only `[force full]` push reaches it through the effective `web_affected`; never a PR, never a dispatch). | Read by `Detect Direct Push` step |
|
|
123
123
|
| `[verbose ci]` | Escalates log detail for one run. Shipped stub flips turbo / Node / Vercel / Supabase / Playwright knobs: `TURBO_LOG_LEVEL=full`, `NODE_OPTIONS=--trace-warnings --trace-deprecation` (a job-level `env:` key, never a `$GITHUB_ENV` write, which the runner rejects while still reporting success), `DEBUG=vercel:*,supabase:*`, plus Playwright `--trace=on` (when E2E stub enabled). Add your stack's equivalents to the same `env:`. Use when `bkit-debug` diagnose returns thin evidence; never for routine pushes (trace.zip files are MB-scale). See `testing.md` for the full knob list and the `--reporter=line` hostile gap. | Read by the job-level `env:` of `bkit-tests-static` (copy the same `env:` onto each lane) |
|
|
124
124
|
| `[skip ci]` / `[skip actions]` | Honoured natively by GitHub Actions, so it suppresses workflow dispatch entirely. Use sparingly: the suppressed run will not appear in `gh run list`, and downstream `workflow_run` triggers will not fire. | Native GitHub behaviour, not a bkit-level toggle |
|
|
@@ -151,7 +151,7 @@ Bkit ships a **mostly flat, wide** scaffold: `bkit-tests-scope` (always-on; read
|
|
|
151
151
|
<!-- prettier-ignore -->
|
|
152
152
|
| Run level | When | Runs | Defers |
|
|
153
153
|
| --- | --- | --- | --- |
|
|
154
|
-
| `none` | `[skip ci]` / `[skip actions]
|
|
154
|
+
| `none` | `[skip ci]` / `[skip actions]`; or release-PR mirror mode (the capstone copies the `dev` push run — § One CI run per dev commit). | Planner, then stop. | Every test lane. |
|
|
155
155
|
| `partial` | Push to `dev` that came from a merged PR, and no `[force build]` / `[force full]`. | Static, unit, integration when `web_affected`, build lanes, migration. `@live` (`bkit-tests-live-web`) still runs on this push when `web_affected`. | `bkit-tests-e2e-web`. Deploy (not the default branch). |
|
|
156
156
|
| `full` | Pull request; `workflow_dispatch`; push to `{{DEFAULT_BRANCH}}`; direct push to `dev` (no merged PR); `[force build]` / `[force full]`. | Partial's lanes, plus `bkit-tests-e2e-web` when `web_affected`. Same spec set as a push (`testing.md` § E2E on PRs). | `@live` off a PR and off a dispatch. On a default-branch push, `bkit-tests-deploy` promotes **before** the E2E / `@live` lanes run; it is not required, and its own `concurrency:` group stops two releases overlapping. Health runs as `workflow_run` after CI. |
|
|
157
157
|
|
|
@@ -168,21 +168,20 @@ A newer run cancels the older one on every event **except the default branch, wh
|
|
|
168
168
|
|
|
169
169
|
A push diffs against the head of the last successful CI run on that branch, not `github.event.before`. Fall back to `github.event.before` only when there is no such run or it is no longer an ancestor. A `workflow_dispatch` has no base commit: short-circuit the affected step to fully affected. `HEAD~1` is only for the delta gates on a dispatch. Markers are inert on dispatch; steer with inputs (§ Commit-message force tags). The planner parses markers once; every lane reads `plan.markers_present`. The only re-read of the commit or PR text is the workflow-level task-runner cache bust (e.g. `TURBO_FORCE`). Plan JSON: validate with `has()` / `!= null`. jq `//` treats `false` as absent and drops a real `run_live: false`.
|
|
170
170
|
|
|
171
|
-
Migration-immutability and slop-delta run on every event against that same base. The starter's copies of those steps are still `pull_request`-only; that `if:` is the pre-planner shape. Point them at the planner base once `bkit-tests-scope` exists.
|
|
171
|
+
Migration-immutability and slop-delta run on every event against that same base. The starter's copies of those steps are still `pull_request`-only; that `if:` is the pre-planner shape. Point them at the planner base once `bkit-tests-scope` exists. Pre-push on a `dev` push resolves the same base (`resolve-push-base.mjs --local`, `.bkit/templates.md` § Git hooks) and exports it as `SLOP_BASE_REF`; a repo-owned migration-immutability pre-push check reads that variable too.
|
|
172
172
|
|
|
173
173
|
Composition guidance:
|
|
174
174
|
|
|
175
|
-
- `cache.outputs.skip` = `none` gate — every step: `if: steps.cache.outputs.skip != 'true'`.
|
|
176
175
|
- `steps.detect.outputs.should_force_build` / `should_run_full` = escalation into `full`.
|
|
177
176
|
- No merged PR on `dev` push (auto cache bust, e.g. `TURBO_FORCE=1`) = recovery signal — partial CI with cache busted.
|
|
178
177
|
- Health (or smoke, when the probe is a script rather than a health URL): separate workflow, `workflow_run` after CI success — not a required check. One of the two, unless the probes differ (§ Smoke trigger plumbing).
|
|
179
|
-
- Capstone `bkit-tests-check` = SOLE branch-protection required check (`bkit setup protect-main` applies it, reading the check name from `bkit.
|
|
178
|
+
- Capstone `bkit-tests-check` = SOLE branch-protection required check (`bkit setup protect-main` applies it, reading the check name from `bkit.testing.ciCapstone` and the workflow from `bkit.testing.ciWorkflow`). Green = expected tiers ran and passed (`green == validated`), not merely "tests job didn't fail". A `partial` or cache-skipped green is not a `full` validation.
|
|
180
179
|
|
|
181
180
|
### Parallel test lanes (one lane per tier)
|
|
182
181
|
|
|
183
182
|
Each tier = **own parallel lane** (job) — `bkit-tests-static` / `-unit` / `-integration` / `-e2e-web` (+ `-migration` / `-live-web`, and optional `-build-ios` / `-e2e-ios` / `-build-android` / `-e2e-android`) — **not** monolithic `bkit-tests` steps. Proven shape: bkit CI + consumer repos run separate lanes. Wall-clock = `max(lane)` not **sum** of serial steps; each tier gets honest coverage + executed-count + job-level permissions; slow tier can't serialise fast ones. Cost: per-lane setup duplicate (checkout / install, shared infra e.g. local DB) — mitigate with a remote task-runner cache (e.g. turbo) + DB service container. Capstone `needs:` **all** lanes; each emits executed-count for non-hollow assertion (`testing.md` § Validated means executed). Starter: `-static` + `-unit`; add lane per tier. Tiny repo: collapse tiers into one lane steps — capstone must assert each tier count via step outputs. E2E full-suite parity + local-vs-preview DB routing → `testing.md` § "E2E on PRs".
|
|
184
183
|
|
|
185
|
-
**Shared resource: reset first, clean up last** (optional). WHEN: 2+ lanes use one long-lived resource. `bkit-tests-reset` runs after scope + migration, takes a lease, and puts the resource in its known state before any of those lanes start. `bkit-tests-cleanup` runs last, `if: always()`, and releases the lease. The lease is what serialises an overlapping PR and `dev` push. The planner names at most one target; an empty target skips both jobs. Capstone reds if a planned reset skipped or either job failed.
|
|
184
|
+
**Shared resource: reset first, clean up last** (optional). WHEN: 2+ lanes use one long-lived resource. `bkit-tests-reset` runs after scope + migration, takes a lease, and puts the resource in its known state before any of those lanes start. `bkit-tests-cleanup` runs last, `if: always()`, and releases the lease. The lease is what serialises an overlapping PR and `dev` push. The planner names at most one target; an empty target skips both jobs. Capstone reds if a planned reset skipped or either job failed. Drop both when the resource is provisioned fresh per run (`testing.md` § Provision backing services fresh — the preferred answer).
|
|
186
185
|
|
|
187
186
|
**Runner size = per-lane lever, only for pole.** Flat graph → one lane defines wall-clock (commonly E2E). Larger runner (more vCPU / RAM) raises internal parallelism (more workers, concurrent E2E projects) → can cut long lane substantially; scope via `runs-on: <your-larger-runner-label>` to **one** lane, default runner elsewhere. Two caveats: (1) **higher per-minute rate** — confirm before adopting (may not appear until first invoice). [Depot](https://depot.dev/docs/github-actions/runner-types) labels (e.g. `depot-ubuntu-24.04-8`) ~30% cheaper than GitHub-hosted; `bkit-ci.yml`, `bkit-cloud.yml` and `bkit-renovate.yml` are templates you own, so set `runs-on` in your copy. (2) **Zero wall-clock** when aimed at non-pole lane: consumer measured bigger E2E runner **+0.0 min** while `@live` stayed pole — worth ~7 min only after `@live` gate removed and E2E became pole. Measure first, re-measure after: pole moves. (3) **A label that does not exist does not fail, so the job queues.** Typo'd / retired label → no error anywhere, job queued indefinitely, run neither reds nor completes. Label set in exactly one place, every `runs-on:` derived from it, planner fails closed on no label.
|
|
188
187
|
|
|
@@ -227,7 +226,7 @@ Optional. A same-repo promotion PR into the default branch — head `dev`, or a
|
|
|
227
226
|
| In progress | Waits (`--max-minutes 170`, job `timeout-minutes` 180 in this mode only) | `4` at the limit |
|
|
228
227
|
| Failed / cancelled / capstone absent or skipped | Red | `1` |
|
|
229
228
|
| None within 10 min (`[skip ci]` at the `dev` tip dispatches none) | Red — push a commit without it to `dev`, re-run the check | `3` |
|
|
230
|
-
| GitHub API error
|
|
229
|
+
| GitHub API error 3x in a row | Red | `20` |
|
|
231
230
|
|
|
232
231
|
**Preconditions — mirroring copies whatever the push run validated:**
|
|
233
232
|
|
|
@@ -243,17 +242,6 @@ Optional. A same-repo promotion PR into the default branch — head `dev`, or a
|
|
|
243
242
|
- Release PR gives up PR-only output (coverage comments, PR-only coverage measurement). None blocks a merge.
|
|
244
243
|
- Feature → `dev` PRs are unaffected: `pull_request ⇒ run_level=full` (§ Consumer CI contract) still holds there, which is what `/bkit-ship`'s gate relies on.
|
|
245
244
|
|
|
246
|
-
### Pull request tree cache (`Check Tree Cache`)
|
|
247
|
-
|
|
248
|
-
A pull request lane skips its suite when the PR's files already passed that lane in a push run. Push and dispatch runs never skip: the run on a push to `dev` or the default branch is the record of what that branch holds.
|
|
249
|
-
|
|
250
|
-
- **Key = files, not commit.** `scripts/ci/lanes/check-tree-cache.mjs` compares the git tree of the checked-out commit (the PR's merge preview) with the head tree of every green push run in the last 7 days. A commit ID cannot match: a PR run tests a merge commit no push run ever had.
|
|
251
|
-
- **The same lane must have run.** A tree match counts only when that run's job of the same name concluded `success`. A `[skip ci]` / `run_level=none` push concludes green with every lane skipped, which proves nothing.
|
|
252
|
-
- **Bypass:** `[force build]` / `[force cache]` in the PR title.
|
|
253
|
-
- **Fails open to running.** Any `gh` / `git` failure → `skip=false`. A missing script (`scripts/ci/lanes/` not copied) → `skip=false` with a notice.
|
|
254
|
-
- **Capstone:** a skipped lane sets `cache_skip=true`, so `bkit-tests-check` asserts no executed-test count for it.
|
|
255
|
-
- **Needs `actions: read`** on every lane with a job-level `permissions:` block (job-level replaces the workflow-level block).
|
|
256
|
-
|
|
257
245
|
## Workflow-file limits GitHub does not enforce visibly
|
|
258
246
|
|
|
259
247
|
**The 21,000-character expression cap.** GitHub compiles every block scalar containing a `${{ … }}` expression as one expression and refuses to compile the workflow past 21,000 characters:
|
|
@@ -274,7 +262,7 @@ Undocumented, and invisible to the toolchain, because the file stays valid YAML,
|
|
|
274
262
|
|
|
275
263
|
- **Trigger scope.** Dispatch jobs gate on `workflow_run.head_repository` being this repo, so a fork PR's CI completion never boots one; on `dev` the same gate excludes `conclusion == 'success'` outright, so a green post-merge run costs zero runner minutes (the merge already happened, so that run only confirms the regression check passed).
|
|
276
264
|
- **FID recovery on `dev`.** No open PR exists, so `{FID}` comes from the squash-merge commit scope (`feat({FID}): …`, primary), falling back to the `bkit:fid` marker in the body of the merged same-repo PR for that SHA. Neither resolving → no-op, no dispatch.
|
|
277
|
-
- **Loop bound.** A `dev` CI failure dispatches `/bkit-debug`
|
|
265
|
+
- **Loop bound.** A `dev` CI failure dispatches `/bkit-debug` until the `{FID}` has `bkit.workflows.debug.fix.maxAttempts` + `bkit.workflows.debug.soak.maxAttempts` distinct failed CI SHAs (2 + 2 by default). `/bkit-debug` creates no branch of its own, so on this surface it remediates on `dev` itself and its push re-triggers this same router; the cap is what terminates that loop. `feat/**` is not capped here (`/bkit-debug` bounds it with the same two limits, counted across every debug run of the feature).
|
|
278
266
|
|
|
279
267
|
**Auto-route contract:** the `bkit [auto route]` free-tier gate marker is threaded by `/bkit-ship` onto the squash-merge `--subject` (not just the sync-merge commit) whenever the issue carries `bkit:auto` — this is what admits `dev`-triggered runs through the existing `bkit-cloud.yml` gate; there is no second gate path. The `[skip ci]` ship-DONE close commit that follows the squash merge never carries the marker and never triggers CI, so it cannot interact with this trigger. Trust surface, kill switch and the cap's tamper caveat → `docs/security.md` § CI Auto-Route Trust.
|
|
280
268
|
|
|
@@ -284,7 +272,7 @@ Undocumented, and invisible to the toolchain, because the file stays valid YAML,
|
|
|
284
272
|
|
|
285
273
|
## Ship gate + bookkeeping
|
|
286
274
|
|
|
287
|
-
`/bkit-ship` is keyed on `bkit branches sync --head=<PR head>`, which reports whether `origin/dev` is an ancestor of the PR head (`basePath`). **Path A** — `dev` has not moved — resumes read-only, no rebase, no bookkeeping commits, no push; merge. **Path B** — `dev` moved — integrates (B1 `
|
|
275
|
+
`/bkit-ship` is keyed on `bkit branches sync --head=<PR head>`, which reports whether `origin/dev` is an ancestor of the PR head (`basePath`). **Path A** — `dev` has not moved — resumes read-only, no rebase, no bookkeeping commits, no push; merge. **Path B** — `dev` moved — integrates (B1 `bkit prs update-branch --only-if-required`, which refreshes the head only when `dev` requires status checks, or B2 worktree + `@bkit-ship-conflict-resolve` + `bkit branches push --mode=feature`, a `--force-with-lease` push), then re-validates when the head moved. A B1 head left unchanged merges at the head CI passed at; the `dev` push run tests the merged result. Both paths end at the same gate: `bkit runs gate --head=<current>` exits 0 (capstone concluded `success`) at the **current** PR head.
|
|
288
276
|
|
|
289
277
|
### Consumer CI contract — `pull_request` resolves to `run_level=full`
|
|
290
278
|
|
|
@@ -294,11 +282,11 @@ The merge gate (`bkit runs gate`) asserts the capstone job's `conclusion=success
|
|
|
294
282
|
- **A docs-only short-circuit** in the host's build-cancel (Vercel `ignoreCommand` / Netlify) that cancels the run mid-flight → capstone may land `cancelled` (gate code 15) or never complete (code 11).
|
|
295
283
|
- **A `[skip ci]` token** in a feature-branch commit subject when the PR opens → GitHub suppresses the `pull_request` run entirely; the PR's `statusCheckRollup` is vacuously empty → no run at head (gate code 10).
|
|
296
284
|
|
|
297
|
-
`bkit runs gate` covers the **common** violation shapes. A skipped non-capstone lane is **reported, not refused**, because the planned-vs-vacuous judgement belongs to the capstone, which takes every lane result as an input and already asserts it per lane. The gate cannot make that judgement itself: the jobs API reports no reason for a skip (a job skipped by a job-level `if:` never reaches a runner, so it carries an empty `steps` array)
|
|
285
|
+
`bkit runs gate` covers the **common** violation shapes. A skipped non-capstone lane is **reported, not refused**, because the planned-vs-vacuous judgement belongs to the capstone, which takes every lane result as an input and already asserts it per lane. The gate cannot make that judgement itself: the jobs API reports no reason for a skip (a job skipped by a job-level `if:` never reaches a runner, so it carries an empty `steps` array).
|
|
298
286
|
|
|
299
|
-
**Code 16 is opt-in, and must stay that way.** It fires only for lanes named in `bkit.
|
|
287
|
+
**Code 16 is opt-in, and must stay that way.** It fires only for lanes named in `bkit.testing.shipGate` (package.json array); the default empty list never refuses. A blanket refuse-on-any-skip is **unsatisfiable by construction** for the CI shape bkit ships: a lane whose `if:` is event-scoped — `bkit-tests-live-web` runs on a push to `dev` or the default branch only — cannot run pre-merge at any head, so a pre-merge gate demanding it refuses every PR forever. Device lanes (`-ios` / `-android`) use the same rule on a pull request and a push; do not treat them as post-merge canaries. Name a lane in `shipGateRequiredLanes` only when your capstone does not assert it and the lane genuinely can run pre-merge. `BKIT_SHIP_GATE_OVERRIDE` remains the audited per-head escape hatch. What still carries the anti-vacuity guarantee is codes 10-15: a run exists, at this head, completed, not cancelled, capstone present, capstone green. Code 14 (green at a superseded head) requires `--branch`: the head-keyed run query is filtered server-side, so a moved head returns the same empty list as a head that never ran, and only a second branch-scoped query separates them. A run that is **present but degraded-but-not-skipped** (e.g. a required lane ran with a reduced test set due to a consumer config the gate cannot see) is a **residual risk named here, not claimed as covered**: the capstone is green because bkit's own `run_level` planner computed `full`; a consumer narrowing inside a lane bkit does not own is invisible to the gate. Keep the capstone (`bkit-tests-check`) as the sole branch-protection required check so `green == validated` survives a docs-only push; do not add per-lane required checks (a hollow lane then green-bars the capstone).
|
|
300
288
|
|
|
301
|
-
**No duplicate dispatch on an already-triggered head (ship Step 9):** a branch push / `gh pr update-branch` fires `pull_request` at the new SHA on its own. The scaffold keys a pull request on `pr-{number}` and a `workflow_dispatch` on `github.ref`. The two are separate groups, so a redundant dispatch is never cancelled and burns a full duplicate run. Ship probes the head whose CI the gate will check (`VALIDATED_HEAD`) with `bkit runs wait --head=<VALIDATED_HEAD> --branch=<branch> --until=present --dispatch-if-absent`, which dispatches only when no run appears; the probe is not a pass condition. The completion wait (`bkit runs wait --head=<VALIDATED_HEAD> --until=completed`) reads only runs at that exact head, so a completed run from a superseded head never answers it. Gate codes 10 / 11 / 14 / 17 re-enter that probe-and-poll only, never the deferred sweep, bounded by `
|
|
289
|
+
**No duplicate dispatch on an already-triggered head (ship Step 9):** a branch push / `gh pr update-branch` fires `pull_request` at the new SHA on its own. The scaffold keys a pull request on `pr-{number}` and a `workflow_dispatch` on `github.ref`. The two are separate groups, so a redundant dispatch is never cancelled and burns a full duplicate run. Ship probes the head whose CI the gate will check (`VALIDATED_HEAD`) with `bkit runs wait --head=<VALIDATED_HEAD> --branch=<branch> --until=present --dispatch-if-absent`, which dispatches only when no run appears; the probe is not a pass condition. The completion wait (`bkit runs wait --head=<VALIDATED_HEAD> --until=completed`) reads only runs at that exact head, so a completed run from a superseded head never answers it. Gate codes 10 / 11 / 14 / 17 re-enter that probe-and-poll only, never the deferred sweep, bounded by `bkit.workflows.ship.merge.maxAttempts`, which counts gate refusals and failed merges together.
|
|
302
290
|
|
|
303
291
|
**No CI run for ship's own docs commit (validated-head carry-forward):** ship's pre-merge `[skip ci]` bookkeeping commit (docs, summaries, ledgers, skill removals) runs no CI. Every path between the last CI-tested commit and the PR head on the bookkeeping allow-list (`bkit ledgers only-bookkeeping`) → `bkit runs gate --validated=<sha>` checks CI at the tested commit; else code 17. Merge still pins the exact head (`--match-head-commit`). Green PR → zero extra runs. Bookkeeping commit merges untested; post-merge `dev` CI (`ship-merge-ci` row) is the backstop. `dev` REQUIRES status checks (classic branch protection or ruleset) → GitHub refuses a head with no run → ship runs CI at the PR head.
|
|
304
292
|
|
|
@@ -319,7 +307,7 @@ Smoke runs **after** deploy, in its own workflow, off the merge gate (what it ac
|
|
|
319
307
|
|
|
320
308
|
- **Deploy happens inside CI** → key smoke to **`workflow_run`** (the CI workflow `completed` + `conclusion == 'success'`). Mind the 3-level `workflow_run` chain cap, because a fourth chained workflow will not fire.
|
|
321
309
|
- **An external platform deploys after merge** (Vercel / Netlify-style Git integration) → key to a **post-deploy** signal — `deployment_status` (`state == 'success'`) or the platform's `repository_dispatch` event — so smoke fires when the deploy is actually **live**, not merely when CI finished. `workflow_run` here smokes a not-yet-serving (or about-to-be-replaced) deployment.
|
|
322
|
-
- Either way: separate workflow, **non-blocking** (never a required check), and wait for the target to be **serving** before probing, because ready
|
|
310
|
+
- Either way: separate workflow, **non-blocking** (never a required check), and wait for the target to be **serving** before probing, because ready != serving (`testing.md` § Deploy-reachability).
|
|
323
311
|
- **Not:** smoke wired into branch protection (it gates observability, not merges), or a `workflow_run`-keyed smoke against an externally-deployed app that probes the old build.
|
|
324
312
|
|
|
325
313
|
## Applying migrations at deploy time
|
|
@@ -392,7 +380,7 @@ Elevated-permission workflows (`packages: write`, `id-token: write`, `contents:
|
|
|
392
380
|
| Renovate (self-hosted runner) | `.bkit/templates/.github/workflows/bkit-renovate.yml` → `.github/workflows/bkit-renovate.yml` | Mend's 3 GB runner OOMs (`kernel-out-of-memory`) on a large pnpm graph. `ubuntu-latest` is ~16 GB. Edit `runs-on` in the copy. |
|
|
393
381
|
| Dependabot | `.bkit/templates/.github/dependabot.yml` → `.github/dependabot.yml` | First-party GitHub. No App. One PR per package. No lockfile-maintenance job. |
|
|
394
382
|
|
|
395
|
-
Use one. Both open PRs for the same packages. `bkit.
|
|
383
|
+
Use one. Both open PRs for the same packages. `bkit.dependencies.updater: "none"` skips the install-time absence advisory.
|
|
396
384
|
|
|
397
385
|
**Gate on known advisories.** Updater PRs never fail CI on a vulnerable version already in the lockfile. Copy `.bkit/templates/scripts/ci/check-dependency-audit.mjs`, its `.test.mjs` and `accepted-advisories.json` → `scripts/ci/`; the `Check Dependency Audit` step (`bkit-tests-static`) self-skips until then. It runs `pnpm audit --json`; a blocking advisory (default high / critical) without an acceptance fails:
|
|
398
386
|
|
|
@@ -447,7 +435,7 @@ Platform auth is a repo secret `BKIT_GH_TOKEN`, never `GITHUB_TOKEN` (those PRs
|
|
|
447
435
|
| Dependabot alerts | Read |
|
|
448
436
|
| Metadata | Read-only |
|
|
449
437
|
|
|
450
|
-
`Commit statuses: Read and write` is what opens the PR. Without it Renovate creates the branch and 403s on commit status.
|
|
438
|
+
`Commit statuses: Read and write` is what opens the PR. Without it Renovate creates the branch and 403s on commit status. A fine-grained PAT has no separate Checks permission. Classic equivalent: scopes `repo`, `workflow`, `security_events` (plus `user:email` for commit authorship). Org-owned tokens cannot read the owner email; set the Actions variable `RENOVATE_GIT_AUTHOR` (for example `Renovate Bot <renovate@your-domain>`).
|
|
451
439
|
|
|
452
440
|
**pnpm 11 on Mend's runner.** A large graph can OOM during `pnpm update --lockfile-only`. The example sets `minimumReleaseAge: "7 days"` and caps `PNPM_WORKERS`. To clear the per-install gate, set `minimumReleaseAge: 0` in `pnpm-workspace.yaml`. Deleting the key does not: pnpm 11 defaults it to 1440. Self-hosted on `ubuntu-latest` has the memory; the freshness setting is still yours to keep or drop.
|
|
453
441
|
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
> **Rules:**
|
|
11
11
|
>
|
|
12
12
|
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
13
|
-
> - Notation: one job per mark — `.bkit/
|
|
13
|
+
> - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
|
|
14
14
|
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
15
15
|
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
|
|
16
16
|
> - No ad-hoc hex — theme tokens only; all colours must support Dark Mode.
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
> **Rules:**
|
|
11
11
|
>
|
|
12
12
|
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
13
|
-
> - Notation: one job per mark — `.bkit/
|
|
13
|
+
> - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
|
|
14
14
|
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
|
|
15
15
|
> - Append-only; one entry per downgraded file / line, archived issue, or raised threshold.
|
|
16
16
|
> - Downgrade only when trigger known / expected; record trigger, not just verdict.
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
> **Rules:**
|
|
11
11
|
>
|
|
12
12
|
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
13
|
-
> - Notation: one job per mark — `.bkit/
|
|
13
|
+
> - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
|
|
14
14
|
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
15
15
|
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
|
|
16
16
|
> - **Never log PII.** Scrub sensitive fields at the source.
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
|
|
19
19
|
## Context Fetch
|
|
20
20
|
|
|
21
|
-
Failure-evidence fetching for `/bkit-debug` (`context-fetch:*` blocks + cloud CLI provisioning) → configure in `.agents/context.md`. Ready-made blocks, one file per provider: `.bkit/templates/context/` (`.bkit/templates.md` § Context-fetch blocks). Author and enable each context there — `ci`, `diff`, `e2e`, `runtime` (default) and the optional `web`. bkit hardcodes no CI host, workflow filename, branch name or e2e framework; a context with no enabled block is fetched for no run and reported `NOT CONFIGURED` every attempt. The `context=web` search host ships in bkit's egress registry, so it needs no declaration; a block whose host is unreachable anyway self-skips → external signal `UNCHECKED`, never "no known upstream issue".
|
|
21
|
+
Failure-evidence fetching for `/bkit-debug` (`context-fetch:*` blocks + cloud CLI provisioning) → configure in `.agents/context.md`. Ready-made blocks, one file per provider: `.bkit/templates/context/` (`.bkit/templates.md` § Context-fetch blocks). Author and enable each context there — `ci`, `diff`, `e2e`, `runtime` (default) and the optional `web`. bkit hardcodes no CI host, workflow filename, branch name, or e2e framework; a context with no enabled block is fetched for no run and reported `NOT CONFIGURED` every attempt. The `context=web` search host ships in bkit's egress registry, so it needs no declaration; a block whose host is unreachable anyway self-skips → external signal `UNCHECKED`, never "no known upstream issue".
|
|
22
22
|
|
|
23
23
|
The workflow commits every captured payload inside an untrusted fence (`===== BEGIN UNTRUSTED =====` … `===== END UNTRUSTED =====`, data-only instruction above it) — fetched web / log / diff text is data, never instructions. A block emits no fence of its own; two wraps read as one nested payload.
|
|
24
24
|
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
> **Rules:**
|
|
11
11
|
>
|
|
12
12
|
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
13
|
-
> - Notation: one job per mark — `.bkit/
|
|
13
|
+
> - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
|
|
14
14
|
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
15
15
|
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
|
|
16
16
|
> - Auth standards live only here. Other docs link, do not restate.
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
> **Rules:**
|
|
11
11
|
>
|
|
12
12
|
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
13
|
-
> - Notation: one job per mark — `.bkit/
|
|
13
|
+
> - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
|
|
14
14
|
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
15
15
|
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
|
|
16
16
|
> - Local seed / test fixtures must never run against remote projects.
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
> **Rules:**
|
|
11
11
|
>
|
|
12
12
|
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
13
|
-
> - Notation: one job per mark — `.bkit/
|
|
13
|
+
> - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
|
|
14
14
|
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
15
15
|
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
|
|
16
16
|
> - List technology and usage; **Why** → `decisions.jsonl`.
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
> **Rules:**
|
|
11
11
|
>
|
|
12
12
|
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
13
|
-
> - Notation: one job per mark — `.bkit/
|
|
13
|
+
> - Notation: one job per mark — `.bkit/authoring.md` § `Notation`.
|
|
14
14
|
> - Describe current state / rules, not reasons / history; state what to do, not why.
|
|
15
15
|
> - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
|
|
16
16
|
> - Tiers strictly separated — Static · Unit · Integration · E2E · @live · Smoke.
|
|
@@ -79,7 +79,7 @@ Scripts these files do not ship, so the plan names them and you write them: mark
|
|
|
79
79
|
- **`bkit-tests-build-web`** — web compile, or the host deployment gate (e.g. Vercel: create this SHA's deployment, publish `deployment_url` + `deployment_id`, leave it un-promoted on the default branch). Emits no `*_ran`.
|
|
80
80
|
- **`bkit-tests-build-ios` / `-e2e-ios` / `bkit-tests-build-android` / `-e2e-android`** (optional) — device build and device flows. Same rule on a PR, a push, and a dispatch: not a post-merge canary. `bkit-tests-e2e-ios` `needs:` scope, migration, reset, `bkit-tests-build-ios`, and `bkit-tests-build-web`. Android matches, with `bkit-tests-build-android`. A planned red reds the capstone. Drop any platform you do not ship. e.g. a hosted build service plus a device-flow runner.
|
|
81
81
|
- **`bkit-tests-live-web`** runs `@live` against the deployed URL (`run_live`; drop the job if no deploy). Push to `dev` or the default branch only, when `web_affected`. Not a pull request. Not a dispatch. `needs:` planner + migration + reset + `bkit-tests-build-web`. Do **not** gate behind static / unit / integration / e2e. A planned failure reds the capstone. `/bkit-ship` still filters a job named `bkit-tests-live`; this name does not match, so the capstone is the gate.
|
|
82
|
-
- **`bkit-tests-reset` / `bkit-tests-cleanup`** (optional; one shared long-lived resource) — reset takes the lease and puts the resource in its known state **before** any lane uses it; cleanup runs last, `if: always()`, and releases the lease. Planner names at most one target. Empty target skips both. Capstone reds if a planned reset skipped or either job failed.
|
|
82
|
+
- **`bkit-tests-reset` / `bkit-tests-cleanup`** (optional; one shared long-lived resource) — reset takes the lease and puts the resource in its known state **before** any lane uses it; cleanup runs last, `if: always()`, and releases the lease. Planner names at most one target. Empty target skips both. Capstone reds if a planned reset skipped or either job failed. Drop both when the resource is provisioned fresh per run (§ Provision backing services fresh — the preferred answer).
|
|
83
83
|
- **Logging probe** (optional step, not a lane) — inside each runtime lane, emit one marked event and ask the error tracker whether it arrived. e.g. Sentry. Skip when that lane did not run the probe.
|
|
84
84
|
- **`bkit-tests-deploy`** (optional) — on a push to the default branch only, **before** the E2E / `@live` lanes. Promotes the exact `deployment_id` `bkit-tests-build-web` published; each tenant lane `needs:` it and starts by proving production serves this run's build (by deployment id). Carries its own `concurrency:` group (`cancel-in-progress: false`) and is not a required check. A red job means the previous deployment stays live.
|
|
85
85
|
- **Health** (optional, separate workflow) — `workflow_run` after CI succeeds on the default branch; smoke the deployment this SHA promoted. Not a required check. Copy the stub to `.github/workflows/health.yml`.
|
|
@@ -260,6 +260,15 @@ A plan's `Derived Test Matrix` (`docs/templates/bkit-plan.md`) is the per-featur
|
|
|
260
260
|
- **Test name:** as the runner reports it, or its last segment (`clamp > keeps a value inside the range` → `keeps a value inside the range`).
|
|
261
261
|
- **The red test stays:** after the red, the test may gain tests or formatting; a weakened, removed or rewritten assertion fails the build's verify.
|
|
262
262
|
|
|
263
|
+
## JUnit reports for bkit
|
|
264
|
+
|
|
265
|
+
`bkit tests run` counts a gate's failures from JUnit XML, not from its log. It empties a report folder before each run and passes its absolute path to the gate as `$BKIT_TEST_REPORT_DIR`.
|
|
266
|
+
|
|
267
|
+
- **Every runner in a gate writes JUnit there** when the variable is set: one file per runner or per run, `*.xml`, any name. Two runs in one gate never write the same file name.
|
|
268
|
+
- **Counted:** failing plus erroring test cases across every file. Skipped cases do not count.
|
|
269
|
+
- **No reports:** `failures` is `null` (count unknown) and a hint says to turn the reporters on. The verdict still comes from the gate's exit code.
|
|
270
|
+
- **Unset variable:** the runner behaves as it always does, so a gate run by hand writes nothing extra.
|
|
271
|
+
|
|
263
272
|
## What each tier must do
|
|
264
273
|
|
|
265
274
|
Tier-by-tier rules: **do** the rule, avoid the **Not** (the failure it prevents). Stack tools (Vitest / Playwright / a Supabase-style local stack / a Vercel-style preview) appear only as worked examples, because the rule is the principle; implement it for your stack.
|
|
@@ -288,8 +297,8 @@ Tier-by-tier rules: **do** the rule, avoid the **Not** (the failure it prevents)
|
|
|
288
297
|
|
|
289
298
|
### Deploy-reachability (between integration and E2E)
|
|
290
299
|
|
|
291
|
-
- Before any tier runs against a freshly-deployed URL, assert it is **actually serving** — **ready
|
|
292
|
-
- Make a missing target an **honest failure**, not a silent skip: assert
|
|
300
|
+
- Before any tier runs against a freshly-deployed URL, assert it is **actually serving** — **ready != serving**. A platform can report a deployment ready while it 404s / 500s; a bare "did the deploy finish" check passes anyway.
|
|
301
|
+
- Make a missing target an **honest failure**, not a silent skip: assert >=1 reachability test actually ran (per-file executed-count), so an unreachable target reds the build instead of green-no-op.
|
|
293
302
|
- **Not:** an E2E suite that "passes" because every spec silently skipped against a target that was never serving.
|
|
294
303
|
|
|
295
304
|
### E2E
|
|
@@ -364,7 +373,15 @@ A tier that needs a stateful backing service (database, cache, queue, search ind
|
|
|
364
373
|
|
|
365
374
|
bkit's `bkit-tests-migration` lane (`bkit-stub:bkit-tests-migration`) is the ready-made home: **always-on** (no job-level `if:` because e2e / live `needs:` it for remote-push ordering; a skip cascades). Replay + seed assert stay plan- / path-gated per-step. On every push to `dev`/`main` the same lane owns remote apply of new migrations (e.g. `supabase db push --linked --include-all`) (un-gated by `run_migration` so it self-heals; after replay so from-empty failure never reaches remote). Capstone asserts `result == success` whenever scope succeeded. Fold into `bkit-tests-check`'s `needs:`.
|
|
366
375
|
|
|
367
|
-
**Local integration freshness.** If your local stack reuses a warm data volume (e.g. Docker + `supabase start`), a bare start can leave migrations unapplied (stale-volume footgun). Prefer a reset-by-default runner over a bare integration run (e.g. `turbo run test:integration`) — mirror local E2E: reset unless `--no-reset`. Shape: `pnpm test:integration:local` → script that starts local stack,
|
|
376
|
+
**Local integration freshness.** If your local stack reuses a warm data volume (e.g. Docker + `supabase start`), a bare start can leave migrations unapplied (stale-volume footgun). Prefer a reset-by-default runner over a bare integration run (e.g. `turbo run test:integration`) — mirror local E2E: reset unless `--no-reset`. Shape: `pnpm test:integration:local` → script that starts local stack, exports its URL + keys, resets from empty (e.g. `supabase db reset --local`), then runs integration (CI passthrough, because CI boots its own hermetic stack).
|
|
377
|
+
|
|
378
|
+
**Local runners never touch env files** (e.g. `.env.local`, `.env.production`; may be the only copy of live credentials):
|
|
379
|
+
|
|
380
|
+
- Target local stack by exporting its values before config loads; loaders (Next, dotenv `override: false`) never override a set key.
|
|
381
|
+
- Blank a hosted key with `export KEY=""`, never `unset` (loader refills unset keys from the file).
|
|
382
|
+
- Never delete, move or hide-and-restore the file (a killed run loses it).
|
|
383
|
+
- Never `vercel env pull` onto it (replaces it with the host's keys only); pull to a scratch file, copy keys across.
|
|
384
|
+
- Guard test fails any tracked script that deletes, moves or overwrites an env file.
|
|
368
385
|
|
|
369
386
|
**"Fresh" means replay-from-empty, not a reused volume.** A bare "start the local stack" command often **reuses an existing data volume** and applies only what's missing, so a "fresh" start can silently run a months-old schema while reporting success. Only a reset / replay from an **empty** store is a freshness proof. And a green replay is not a green **seed**: assert the seed actually loaded (a known row exists), because the reset can exit 0 while a conditional insert no-ops or the seed aborts mid-file (§ Migration-replay + seed carries the full seed-determinism rules).
|
|
370
387
|
|
|
@@ -374,9 +391,9 @@ bkit's `bkit-tests-migration` lane (`bkit-stub:bkit-tests-migration`) is the rea
|
|
|
374
391
|
|
|
375
392
|
Beyond the gates above, three practices raise confidence further — opt-in, not baseline:
|
|
376
393
|
|
|
377
|
-
- **Mutation testing** (e.g. StrykerJS over a Vitest suite) automates the "executed
|
|
394
|
+
- **Mutation testing** (e.g. StrykerJS over a Vitest suite) automates the "executed != exercised" intent: it injects bugs into production code and fails when no test catches them. Run it locally, on demand. It is not a CI lane and not a nightly workflow. Gate a local run on a survival-score threshold, never 100% (equivalent mutants make perfection unreachable). Capstone asks "did tests run?"; mutation asks "do they catch injected bugs?".
|
|
378
395
|
- **E2E sharding** (`--shard` matrix + report merge) cuts wall-clock on a large browser suite, but it is **gated on per-shard data isolation** (the unique-ID independence above). A single shared seed pins `workers: 1` and blocks sharding until the data is isolated. Isolated data is still not enough once several invocations share one job — § Concurrent invocations collide on disk, not just in the database.
|
|
379
|
-
- **Bounded flaky-retry with tracking.** A capped retry on the flake-prone E2E tier is low-risk **only** when paired with explicit flake **tracking**, because an auto-retry that silently passes hides a real regression, the inverse of "validated
|
|
396
|
+
- **Bounded flaky-retry with tracking.** A capped retry on the flake-prone E2E tier is low-risk **only** when paired with explicit flake **tracking**, because an auto-retry that silently passes hides a real regression, the inverse of "validated != didn't fail".
|
|
380
397
|
|
|
381
398
|
## Coverage on PRs
|
|
382
399
|
|
|
@@ -390,11 +407,11 @@ Report coverage on each PR **without a paid product or a third-party service**
|
|
|
390
407
|
- **Reporters are load-bearing.** The action reads `coverage-summary.json` (from the `json-summary` reporter, mandatory) and `coverage-final.json` (from `json`, required for `file-coverage-mode: changes`). Enable both in `coverage.reporter` or the step no-ops.
|
|
391
408
|
- **Two runs, separate dirs.** `vitest run --coverage --coverage.reportsDirectory=coverage/unit --exclude '**/*.integration.test.ts'` for unit; a second run into `coverage/integration` for the integration tier. Separate dirs also avoid the last-writer-wins **clobber** a second same-dir `--coverage` run would cause.
|
|
392
409
|
- **Thresholds are opt-in and per tier:**
|
|
393
|
-
- **Unit = the gate.** Put `coverage.thresholds.branches: <current>` in a `vitest.unit.config.ts` (`mergeConfig` over `vitest.config`) that **only** the unit run loads via `-c`, because **branches** is the meaningful floor (line / statement % overstates confidence); set it to your **current** coverage and ratchet up. vitest coverage is per-**run** (root config), **not** per-project, so `projects` does **not** scope it and a `thresholds` block in `vitest.config` would red **both** runs; the `-c` file is what keeps the gate off integration. A `--coverage.thresholds.branches=<n>` CLI flag also gates, but the report step cannot read it. 80% is convention, not best practice, because a fetishised high bar breeds assertion-free line-touching tests; the executed
|
|
410
|
+
- **Unit = the gate.** Put `coverage.thresholds.branches: <current>` in a `vitest.unit.config.ts` (`mergeConfig` over `vitest.config`) that **only** the unit run loads via `-c`, because **branches** is the meaningful floor (line / statement % overstates confidence); set it to your **current** coverage and ratchet up. vitest coverage is per-**run** (root config), **not** per-project, so `projects` does **not** scope it and a `thresholds` block in `vitest.config` would red **both** runs; the `-c` file is what keeps the gate off integration. A `--coverage.thresholds.branches=<n>` CLI flag also gates, but the report step cannot read it. 80% is convention, not best practice, because a fetishised high bar breeds assertion-free line-touching tests; the executed-!=-exercised rule (§ Validated means executed) matters far more than the number.
|
|
394
411
|
- **Floor beside the figure.** The unit report step runs on **every** event (a red run too, via `!cancelled()` plus a `hashFiles` guard), passes `vite-config-path: vitest.unit.config.ts`, and comments only on same-repo PRs (`comment-on: pr`, else `none`), so every job summary, pushes included, shows the measured % against its 🎯 floor. The action regex-matches `<metric>: <number>` in that file's raw text: keep the floor on one unquoted line and no other metric name + colon + number in the file, because a broken match drops the target silently while the gate keeps passing.
|
|
395
412
|
- **Integration = report-only.** Gate integration on **execution** (the capstone's `integration_ran > 0`), **not** a %. A whole-repo integration % is denominator-noise, because integration covers boundaries / flows, not pure logic, and rarely drives every branch, so a hard threshold on it punishes the correct pyramid shape. If you want a real integration %, add `--coverage.include='src/server/**'` on the integration run (same CLI-flag idiom as `--exclude`) to scope it to the integration surface, **then** set a floor, or **ratchet from current** — never a number picked from thin air.
|
|
396
413
|
- **Share the unit gate with the build workflow.** Put the unit run (`vitest run -c vitest.unit.config.ts --coverage …`) in a `test:coverage:unit` script and chain it into `bkit:gate:static-unit` in place of `pnpm test`, never beside it (both run every unit test, so each runs twice) — the CI unit lane calls the script, `/bkit-build` Run Tests calls the gate, so the floor has **one source** and a regression fails in the worktree, not only on the PR. Never duplicate the command and sync it by comment, because that drifts. The build runs only the deepest declared `bkit:gate:*`, never the script by name: **left out of the chain, it never gates the build**. (bkit's own repo does exactly this.)
|
|
397
|
-
- **Permissions.** The report steps need `pull-requests: write` — declare it at **job level** on the lane that posts. Job-level `permissions:` **replaces** the workflow-level block (not additive),
|
|
414
|
+
- **Permissions.** The report steps need `pull-requests: write` — declare it at **job level** on the lane that posts. Job-level `permissions:` **replaces** the workflow-level block (not additive), so re-include `contents: read` too or the checkout breaks. **Separate lanes:** with a lane per tier (recommended — see `deployments.md` § Parallel test lanes), each coverage comment posts from its own lane (unit-cov → `bkit-tests-unit`, integration-cov → `bkit-tests-integration`), so put the block on **each** lane that reports. With the combined starter, both live on `bkit-tests-unit`.
|
|
398
415
|
- **Fork PRs.** `GITHUB_TOKEN` is read-only for PRs from a fork, so commenting fails — the shipped unit step sets `comment-on: none` there (its job summary still lands) and the integration step's `head.repo == repo` guard skips it; adopt the action's `workflow_run` two-workflow pattern if you must comment on fork PRs. The integration step is also guarded on `hashFiles(...)` so a repo with **no integration tier** skips it cleanly.
|
|
399
416
|
- **Base-branch delta** (▲▼ vs the default branch) is **not** shipped by default, because it needs the base's `coverage-summary.json` (a second run or a stored artifact); wire the action's `json-summary-compare-path` if you want it.
|
|
400
417
|
|
|
@@ -406,7 +423,7 @@ The **E2E tier** (`bkit-stub:e2e-coverage`) reports Playwright coverage the same
|
|
|
406
423
|
- **Report with Monocart.** `monocart-coverage-reports` (wired via the `monocart-reporter` Playwright reporter) ingests **either** V8 or Istanbul input and emits Istanbul-format `coverage/e2e/coverage-summary.json` + `coverage-final.json` — the **same two files** the vitest action reads (`reports: ['json-summary', 'json', 'lcov']`), so no new commenter is needed.
|
|
407
424
|
- **Comment by reuse.** Point `davelosert/vitest-coverage-report-action@v2` at `coverage/e2e` with `name: e2e`. If Monocart's `coverage-final.json` isn't accepted for `file-coverage-mode: changes`, drop to `file-coverage-mode: all`, or comment via a cobertura action (`irongut/CodeCoverageSummary`) on Monocart's `cobertura` report.
|
|
408
425
|
- **Report-only — no threshold by default.** A whole-app E2E % is denominator-noise (E2E exercises user **flows**, not every branch), so gate the tier on the **E2E step succeeding**, not a number. For a real E2E %, scope Monocart's `entryFilter`/`sourceFilter` to the surface E2E is meant to cover, **then** ratchet from current — never a picked number.
|
|
409
|
-
- **Permissions / forks.** The E2E coverage report runs in the **`bkit-tests-e2e-web` lane** (or, with the combined starter, in `bkit-tests-unit`), and needs that lane's job-level `pull-requests: write` + `
|
|
426
|
+
- **Permissions / forks.** The E2E coverage report runs in the **`bkit-tests-e2e-web` lane** (or, with the combined starter, in `bkit-tests-unit`), and needs that lane's job-level `pull-requests: write` + `contents: read` block, or the comment can't post. The `head.repo == repo` guard skips fork PRs; a `hashFiles('coverage/e2e/coverage-summary.json')` guard skips repos with no E2E coverage.
|
|
410
427
|
|
|
411
428
|
## CI verbosity (`[verbose ci]`)
|
|
412
429
|
|
|
@@ -137,7 +137,7 @@ if [ -f .agents/context.md ]; then
|
|
|
137
137
|
if [ ! -x "$BKIT" ] || ! command -v jq >/dev/null 2>&1; then
|
|
138
138
|
log "context-fetch provisioning: SKIPPED — bkit (node_modules/.bin/bkit) or jq is missing. Fix: a working 'pnpm install' and the cloud setup script from .claude/bkit-cloud.md."
|
|
139
139
|
else
|
|
140
|
-
PROVISION=$("$BKIT" context list-blocks 2>/dev/null | jq -r '.provision[]' 2>/dev/null || true)
|
|
140
|
+
PROVISION=$("$BKIT" context list-blocks --json 2>/dev/null | jq -r '.provision[]' 2>/dev/null || true)
|
|
141
141
|
if [ -n "$PROVISION" ]; then
|
|
142
142
|
log "provisioning context-fetch CLIs from .agents/context.md"
|
|
143
143
|
# pnpm refuses `add -g` unless its global-bin dir is on PATH (corepack pnpm skips
|
|
@@ -8,9 +8,9 @@ body:
|
|
|
8
8
|
- type: markdown
|
|
9
9
|
attributes:
|
|
10
10
|
value: |
|
|
11
|
-
Write this as the plan: a build with no plan
|
|
12
|
-
- `/bkit-plan #<issue number>` turns it into a checked plan; the build then proves each **
|
|
13
|
-
- `/bkit-build #<issue number>`
|
|
11
|
+
Write this as the plan: a build with no plan converts this issue into one.
|
|
12
|
+
- `/bkit-plan #<issue number>` turns it into a checked plan; the build then proves each **TEST FIRST** test fails before its code exists.
|
|
13
|
+
- `/bkit-build #<issue number>` converts this issue into a plan, then builds it and proves each **TEST FIRST** test fails before its code exists.
|
|
14
14
|
- `build:lite` builds from this issue too but checks nothing: no failing-test proof, gates, PR or CI.
|
|
15
15
|
|
|
16
16
|
Keep the title short: it names the feature folder. Nothing ticks boxes in an issue.
|
|
@@ -56,9 +56,30 @@ body:
|
|
|
56
56
|
attributes:
|
|
57
57
|
label: Tasks
|
|
58
58
|
description: |
|
|
59
|
-
In build order, one line
|
|
59
|
+
In build order, preferably in this shape, the same group and task blocks a plan uses: groups of up to `bkit.workflows.tasks.maxPerGroup` tasks (default 3) and `bkit.workflows.tasks.maxTestsPerGroup` **TEST FIRST** tests (default 15), each task a block, task numbers unique across the issue. **CREATE** / **READ** / **UPDATE** / **DELETE** = one line per file the task touches, as `` `symbol` in `file`: what to do `` or `` `file`: what to do ``. **DEPENDS ON** = the numbers of tasks it builds on, in the same or an earlier group. **DONE WHEN** = a check you can verify in the code (file exists, test passes, behaviour observable). **TEST FIRST** = the matrix tests that fail before the code exists, 1 to `bkit.workflows.tasks.maxTestsPerTask` per task (default 10) across up to `bkit.workflows.tasks.maxTestFilesPerTask` test files (default 3), one line each as `` `test file` `test name` fails on what goes wrong ``; or `n/a — reason` for docs, config, a pure refactor, or E2E / @live only. **TEST EXCEPTION** = written only by the owner: tests whose test-order gap you accept, each as in **TEST FIRST** ending `— reason`; it counts once committed alone in the plan. A **TEST EXCEPTION** written here is a request: the build copies it word for word, stops on it, and the owner confirms it at the build's Decision Pause, where Accept rewrites it with the owner's reason and date. Free text works too: the build converts it. A plan file for this issue wins: once one exists, the build reads its tasks only from the plan, never from here.
|
|
60
60
|
placeholder: |
|
|
61
|
-
|
|
61
|
+
<!-- bkit:group 1 start -->
|
|
62
|
+
### GROUP 1: Saving items
|
|
63
|
+
<!-- bkit:task 1 start -->
|
|
64
|
+
- [ ] **TASK 1:** Refuse an empty item name
|
|
65
|
+
- **UPDATE:** `saveItem` in `path/to/items`: refuse an empty name
|
|
66
|
+
- **READ:** `path/to/list`: where saved items show
|
|
67
|
+
- **DONE WHEN:** saving an empty name stores nothing and shows why
|
|
68
|
+
- **TEST FIRST:**
|
|
69
|
+
- `path/to/list.test` `rejects an empty name` fails on an empty name being saved
|
|
70
|
+
<!-- bkit:task 1 end -->
|
|
71
|
+
<!-- bkit:task 2 start -->
|
|
72
|
+
- [ ] **TASK 2:** Show saved items in the list
|
|
73
|
+
- **CREATE:** `path/to/list-row`: one row per saved item
|
|
74
|
+
- **DELETE:** `ItemPreview` in `path/to/list`: replaced by the new row
|
|
75
|
+
- **DEPENDS ON:** 1
|
|
76
|
+
- **DONE WHEN:** a saved item appears in the list
|
|
77
|
+
- **TEST FIRST:**
|
|
78
|
+
- `path/to/list.test` `shows a saved item` fails on the list staying empty
|
|
79
|
+
- **TEST EXCEPTION:**
|
|
80
|
+
- `path/to/list.test` `shows a saved item` — the old preview already shows saved items, so it cannot fail first
|
|
81
|
+
<!-- bkit:task 2 end -->
|
|
82
|
+
<!-- bkit:group 1 end -->
|
|
62
83
|
validations:
|
|
63
84
|
required: true
|
|
64
85
|
- type: textarea
|