@cbartens/bkit 6.1.1 → 6.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +14 -12
- package/.bkit/core/.agents/docs.md +1 -11
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
- package/.bkit/core/.agents/rules.md +22 -9
- package/.bkit/core/.bkit/README.md +13 -11
- package/.bkit/core/.bkit/authoring.md +58 -13
- package/.bkit/core/.bkit/cli.md +42 -32
- package/.bkit/core/.bkit/cloud.md +93 -30
- package/.bkit/core/.bkit/install.md +55 -16
- package/.bkit/core/.bkit/jsonl.md +24 -7
- package/.bkit/core/.bkit/pipeline.md +8 -8
- package/.bkit/core/.bkit/prompts.md +160 -43
- package/.bkit/core/.bkit/providers.md +97 -36
- package/.bkit/core/.bkit/templates.md +162 -34
- package/.bkit/core/.bkit/trackers.md +39 -6
- package/.bkit/core/.bkit/workflows.md +344 -136
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
- package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
- package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/docs/templates/bkit-plan.md +38 -8
- package/.bkit/core/engine/checks/after/auth.ts +118 -47
- package/.bkit/core/engine/checks/after/github.ts +89 -37
- package/.bkit/core/engine/checks/after/index.ts +15 -3
- package/.bkit/core/engine/checks/after/tools.ts +245 -1
- package/.bkit/core/engine/checks/before/files.ts +59 -1
- package/.bkit/core/engine/checks/before/index.ts +8 -0
- package/.bkit/core/engine/checks/status-holes.ts +20 -26
- package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
- package/.bkit/core/engine/checks/tips/detect.ts +36 -3
- package/.bkit/core/engine/checks/tips/index.ts +1 -1
- package/.bkit/core/engine/cli.ts +13 -13
- package/.bkit/core/engine/commands/ci/ci.ts +64 -11
- package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
- package/.bkit/core/engine/commands/install/install.ts +28 -25
- package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
- package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
- package/.bkit/core/engine/commands/land.ts +2 -3
- package/.bkit/core/engine/commands/lib.ts +394 -39
- package/.bkit/core/engine/commands/registry.ts +1 -1
- package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
- package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
- package/.bkit/core/engine/commands/workflow/context.ts +71 -10
- package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
- package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
- package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
- package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
- package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
- package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
- package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
- package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
- package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
- package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
- package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
- package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
- package/.bkit/core/engine/commands/workflow/status.ts +324 -11
- package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
- package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
- package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
- package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
- package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
- package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
- package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
- package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
- package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
- package/.bkit/core/engine/install/cloud-env.ts +38 -10
- package/.bkit/core/engine/install/managed-block.ts +105 -0
- package/.bkit/core/engine/install/manifest.ts +7 -1
- package/.bkit/core/engine/install/modules/claude.ts +6 -2
- package/.bkit/core/engine/install/modules/cloud.ts +84 -95
- package/.bkit/core/engine/install/modules/codex.ts +10 -2
- package/.bkit/core/engine/install/modules/core.ts +148 -14
- package/.bkit/core/engine/install/modules/opencode.ts +18 -23
- package/.bkit/core/engine/install/network-allowlist.ts +8 -3
- package/.bkit/core/engine/install/project-docs.ts +650 -0
- package/.bkit/core/engine/install/template-copies.ts +58 -5
- package/.bkit/core/engine/install/write.ts +128 -7
- package/.bkit/core/engine/ledgers/journal.ts +18 -10
- package/.bkit/core/engine/ledgers/migrate.ts +20 -8
- package/.bkit/core/engine/ledgers/status.ts +604 -8
- package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
- package/.bkit/core/engine/render/trackers.ts +3 -1
- package/.bkit/core/engine/shared/package-manager.ts +7 -3
- package/.bkit/core/engine/shared/settings.ts +12 -1
- package/.bkit/core/engine/shared/text.ts +14 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
- package/.bkit/core/engine/tools/instructions.ts +116 -20
- package/.bkit/core/hooks/antigravity-hook.js +20 -4
- package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
- package/.bkit/core/hooks/gateguard-engine.js +249 -23
- package/.bkit/core/hooks/guardrails-deny.js +167 -0
- package/.bkit/core/hooks/guardrails-read.js +3 -3
- package/.bkit/core/hooks/guardrails-shell.js +1122 -167
- package/.bkit/core/hooks/guardrails-tiers.js +247 -176
- package/.bkit/core/hooks/preflight-tracker.sh +219 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
- package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
- package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
- package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
- package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
- package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
- package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
- package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
- package/.bkit/core/prompts/bkit-design-generate.md +6 -4
- package/.bkit/core/prompts/bkit-design-organise.md +4 -3
- package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
- package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
- package/.bkit/core/prompts/bkit-design-spike.md +4 -3
- package/.bkit/core/prompts/bkit-design-update.md +6 -4
- package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
- package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
- package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
- package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
- package/.bkit/core/prompts/bkit-plan-update.md +22 -8
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
- package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
- package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
- package/.bkit/core/workflows/bkit-auto.md +23 -11
- package/.bkit/core/workflows/bkit-build.md +331 -100
- package/.bkit/core/workflows/bkit-debug.md +135 -64
- package/.bkit/core/workflows/bkit-design.md +58 -32
- package/.bkit/core/workflows/bkit-plan.md +73 -45
- package/.bkit/core/workflows/bkit-ship.md +233 -167
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
- package/.bkit/shared/.bkit/.env.example +5 -0
- package/.bkit/shared/.claude/bkit-cloud.md +7 -7
- package/.bkit/shared/.claude/settings.json +5 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
- package/.bkit/shared/.cursor/hooks.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
- package/.bkit/templates/.cursor/Dockerfile +7 -7
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
- package/.bkit/templates/.github/dependabot.yml +5 -0
- package/.bkit/templates/.github/renovate.json5 +5 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
- package/.bkit/templates/.husky/pre-push +123 -6
- package/.bkit/templates/context/bkit-serena.md +1 -1
- package/.bkit/templates/docs/architecture.md +98 -0
- package/.bkit/templates/docs/capabilities.md +33 -37
- package/.bkit/templates/docs/components.md +142 -0
- package/.bkit/templates/docs/data-schema.md +87 -0
- package/.bkit/{shared → templates}/docs/deployments.md +128 -142
- package/.bkit/templates/docs/design.md +117 -0
- package/.bkit/templates/docs/noise.md +54 -0
- package/.bkit/templates/docs/observability.md +99 -0
- package/.bkit/templates/docs/security.md +137 -0
- package/.bkit/templates/docs/setup.md +93 -0
- package/.bkit/templates/docs/technology.md +70 -0
- package/.bkit/{shared → templates}/docs/testing.md +200 -87
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +228 -35
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +270 -2
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +92 -63
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
- package/.bkit/templates/slop-scan.config.json +2 -0
- package/CHANGELOG.md +64 -0
- package/DETAILS.md +24 -19
- package/README.md +1 -1
- package/dist/checks/after/auth.js +114 -46
- package/dist/checks/after/github.js +77 -35
- package/dist/checks/after/index.js +12 -3
- package/dist/checks/after/tools.js +224 -1
- package/dist/checks/before/files.js +59 -1
- package/dist/checks/before/index.js +7 -1
- package/dist/checks/status-holes.js +20 -21
- package/dist/checks/tips/catalogue.js +99 -10
- package/dist/checks/tips/detect.js +35 -3
- package/dist/checks/tips/index.js +1 -1
- package/dist/cli.js +13 -13
- package/dist/commands/ci/ci.js +56 -12
- package/dist/commands/ci/push-gate.js +79 -44
- package/dist/commands/install/install.js +23 -22
- package/dist/commands/install/uninstall.js +36 -30
- package/dist/commands/install/upgrade.js +10 -2
- package/dist/commands/land.js +2 -3
- package/dist/commands/lib.js +323 -25
- package/dist/commands/workflow/branches.js +312 -72
- package/dist/commands/workflow/challenge.js +66 -13
- package/dist/commands/workflow/context.js +46 -10
- package/dist/commands/workflow/counters.js +231 -23
- package/dist/commands/workflow/decisions.js +221 -106
- package/dist/commands/workflow/disk.js +2 -1
- package/dist/commands/workflow/feature-base.js +60 -0
- package/dist/commands/workflow/issues.js +243 -15
- package/dist/commands/workflow/junit.js +137 -0
- package/dist/commands/workflow/ledgers.js +726 -112
- package/dist/commands/workflow/locks.js +150 -29
- package/dist/commands/workflow/loops.js +67 -0
- package/dist/commands/workflow/open-decision.js +199 -0
- package/dist/commands/workflow/plan-blocks.js +6 -0
- package/dist/commands/workflow/plans.js +1 -1
- package/dist/commands/workflow/prs.js +272 -16
- package/dist/commands/workflow/repo.js +1 -1
- package/dist/commands/workflow/run-facts.js +6 -0
- package/dist/commands/workflow/runs.js +747 -155
- package/dist/commands/workflow/runtime.js +8 -4
- package/dist/commands/workflow/status.js +259 -13
- package/dist/commands/workflow/step-table.js +41 -15
- package/dist/commands/workflow/steps.js +530 -26
- package/dist/commands/workflow/summary-findings.js +1 -1
- package/dist/commands/workflow/summary.js +289 -8
- package/dist/commands/workflow/tasks.js +294 -27
- package/dist/commands/workflow/tests-base.js +266 -0
- package/dist/commands/workflow/tests-changed.js +130 -56
- package/dist/commands/workflow/tests-jump.js +77 -0
- package/dist/commands/workflow/tests.js +608 -131
- package/dist/commands/workflow/tracker.js +920 -112
- package/dist/commands/workflow/workflows.js +80 -59
- package/dist/commands/workflow/worktrees.js +387 -58
- package/dist/install/cloud-env.js +32 -10
- package/dist/install/managed-block.js +101 -0
- package/dist/install/manifest.js +7 -1
- package/dist/install/modules/claude.js +6 -2
- package/dist/install/modules/cloud.js +73 -86
- package/dist/install/modules/codex.js +9 -2
- package/dist/install/modules/core.js +133 -14
- package/dist/install/modules/opencode.js +18 -23
- package/dist/install/network-allowlist.js +8 -3
- package/dist/install/project-docs.js +551 -0
- package/dist/install/template-copies.js +55 -5
- package/dist/install/write.js +117 -5
- package/dist/ledgers/journal.js +10 -8
- package/dist/ledgers/migrate.js +20 -9
- package/dist/ledgers/status.js +461 -8
- package/dist/ledgers/telemetry.js +71 -13
- package/dist/render/trackers.js +3 -1
- package/dist/shared/package-manager.js +7 -2
- package/dist/shared/settings.js +8 -0
- package/dist/shared/text.js +13 -0
- package/dist/tools/instructions-sources.js +1 -0
- package/dist/tools/instructions.js +97 -24
- package/package.json +22 -15
- package/.bkit/core/hooks/preflight-linear.sh +0 -73
- package/.bkit/shared/docs/architecture.md +0 -16
- package/.bkit/shared/docs/data-schema.md +0 -16
- package/.bkit/shared/docs/design.md +0 -38
- package/.bkit/shared/docs/noise.md +0 -20
- package/.bkit/shared/docs/observability.md +0 -22
- package/.bkit/shared/docs/security.md +0 -62
- package/.bkit/shared/docs/setup.md +0 -52
- package/.bkit/shared/docs/technology.md +0 -15
- /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
- /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
|
@@ -66,7 +66,7 @@ jobs:
|
|
|
66
66
|
# app-id: ${{ secrets.RENOVATE_APP_ID }}
|
|
67
67
|
# private-key: ${{ secrets.RENOVATE_APP_PRIVATE_KEY }}
|
|
68
68
|
# then set `token: ${{ steps.app-token.outputs.token }}` below.
|
|
69
|
-
- uses: renovatebot/github-action@
|
|
69
|
+
- uses: renovatebot/github-action@1c0cf989c02653fba0efe7ca5772338860ca71dc # v46.3.12
|
|
70
70
|
with:
|
|
71
71
|
# PAT secret (default). FINE-GRAINED repository permissions (this repo):
|
|
72
72
|
# Contents: Read and write · Pull requests: Read and write ·
|
|
@@ -85,7 +85,7 @@ jobs:
|
|
|
85
85
|
# uses GitHub releases (they carry publish dates, so `minimumReleaseAge` applies);
|
|
86
86
|
# the image tags on ghcr.io carry none.
|
|
87
87
|
# renovate: datasource=github-releases depName=renovatebot/renovate
|
|
88
|
-
renovate-version: "44.
|
|
88
|
+
renovate-version: "44.221.6"
|
|
89
89
|
env:
|
|
90
90
|
# Scope to THIS repo only — never org-wide autodiscover.
|
|
91
91
|
RENOVATE_REPOSITORIES: ${{ github.repository }}
|
|
@@ -24,7 +24,10 @@ set -e
|
|
|
24
24
|
# background, still has the whole run. The path is printed first (tail -f it while the push
|
|
25
25
|
# runs) and last, with the exit code. Git's ref list on stdin reaches the inner run unchanged,
|
|
26
26
|
# and the hook exits with the inner run's code. Output goes to stderr, where git sends a
|
|
27
|
-
# hook's output anyway.
|
|
27
|
+
# hook's output anyway. When the repo has an `.envrc`, `direnv` is on PATH and CI is unset, the
|
|
28
|
+
# inner run goes through `direnv exec .`, so the gate sees the repo's variables whatever shell
|
|
29
|
+
# pushed; an `.envrc` that fails to load blocks first with direnv's own output, plus the
|
|
30
|
+
# `direnv allow .` fix when direnv reports it untrusted. The keys in `.bkit/.env` are unset for the gate. `git push --no-verify`, and a checkout without husky installed (a
|
|
28
31
|
# linked worktree), run no hook and write no log.
|
|
29
32
|
if [ -z "${BKIT_PRE_PUSH_LOGGED:-}" ]; then
|
|
30
33
|
PRE_PUSH_LOG=tmp/pre-push.log
|
|
@@ -33,7 +36,24 @@ if [ -z "${BKIT_PRE_PUSH_LOGGED:-}" ]; then
|
|
|
33
36
|
{
|
|
34
37
|
echo "[pre-push] log: $PRE_PUSH_LOG"
|
|
35
38
|
pre_push_rc=0
|
|
36
|
-
|
|
39
|
+
if [ -f .envrc ] && [ -z "${CI:-}" ] && command -v direnv > /dev/null 2>&1; then
|
|
40
|
+
if direnv_probe=$(direnv exec . true < /dev/null 2>&1); then
|
|
41
|
+
BKIT_PRE_PUSH_LOGGED=1 FORCE_COLOR=1 direnv exec . sh "$0" "$@" 2>&1 || pre_push_rc=$?
|
|
42
|
+
else
|
|
43
|
+
printf '%s\n' "$direnv_probe"
|
|
44
|
+
case "$direnv_probe" in
|
|
45
|
+
*" is blocked"* | *" not allowed"*)
|
|
46
|
+
echo "[pre-push] .envrc is not trusted: run \`direnv allow .\` in this folder, then push again."
|
|
47
|
+
;;
|
|
48
|
+
*)
|
|
49
|
+
echo "[pre-push] .envrc failed to load (direnv output above): fix it, then push again."
|
|
50
|
+
;;
|
|
51
|
+
esac
|
|
52
|
+
pre_push_rc=1
|
|
53
|
+
fi
|
|
54
|
+
else
|
|
55
|
+
BKIT_PRE_PUSH_LOGGED=1 FORCE_COLOR=1 sh "$0" "$@" 2>&1 || pre_push_rc=$?
|
|
56
|
+
fi
|
|
37
57
|
echo "[pre-push] log: $PRE_PUSH_LOG (exit $pre_push_rc)"
|
|
38
58
|
echo "$pre_push_rc" > "$PRE_PUSH_RC_FILE"
|
|
39
59
|
} | tee "$PRE_PUSH_LOG" >&2
|
|
@@ -42,6 +62,22 @@ if [ -z "${BKIT_PRE_PUSH_LOGGED:-}" ]; then
|
|
|
42
62
|
exit "$pre_push_rc"
|
|
43
63
|
fi
|
|
44
64
|
|
|
65
|
+
# The bkit tooling keys are unset for the gate: its tests, lint plugins and dependency code never
|
|
66
|
+
# need them, and their output lands in the agent-readable log. Two sources: the fixed list
|
|
67
|
+
# (.bkit/templates.md § Git hooks — Husky), whichever path loaded them (cloud dashboard env, an app
|
|
68
|
+
# env file, ~/.zshrc, launchd), and every key `.bkit/.env` names, in direnv's dotenv grammar
|
|
69
|
+
# (`KEY=v`, `KEY = v`, `KEY: v`, optional `export `).
|
|
70
|
+
for gate_key in BKIT_GH_TOKEN BKIT_LINEAR_API_KEY BKIT_JIRA_API_KEY BKIT_ANTHROPIC_API_KEY \
|
|
71
|
+
BKIT_CURSOR_API_KEY BKIT_OPENCODE_API_KEY BKIT_OPENROUTER_API_KEY BKIT_OLLAMA_API_KEY \
|
|
72
|
+
BKIT_OPENAI_API_KEY; do
|
|
73
|
+
unset "$gate_key"
|
|
74
|
+
done
|
|
75
|
+
if [ -f .bkit/.env ]; then
|
|
76
|
+
for gate_key in $(sed -n 's/^[[:space:]]*\(export[[:space:]][[:space:]]*\)\{0,1\}\([A-Za-z_][A-Za-z0-9_]*\)[[:space:]]*[=:].*/\2/p' .bkit/.env); do
|
|
77
|
+
unset "$gate_key"
|
|
78
|
+
done
|
|
79
|
+
fi
|
|
80
|
+
|
|
45
81
|
# Git exports GIT_DIR to a hook and everything it starts (from a linked worktree:
|
|
46
82
|
# <main>/.git/worktrees/<name>). It beats a child's cwd and -C, so a test's `git -C "$tmp" init`
|
|
47
83
|
# re-initialises this repo (core.bare=true in the shared .git/config) and a fixture's
|
|
@@ -106,6 +142,45 @@ case "$HEAD_SUBJECT" in
|
|
|
106
142
|
'Revert "'*) IS_REVERT=1 ;;
|
|
107
143
|
esac
|
|
108
144
|
|
|
145
|
+
# Open-PR lookup: one `gh pr list` for every branch except dev / main, shared by the
|
|
146
|
+
# CI-suppressor guard (the number) and the PR conflict check (the number and its base).
|
|
147
|
+
# gh absent or failing leaves PR_LOOKUP naming why; the check that needs an answer warns.
|
|
148
|
+
OPEN_PR=""
|
|
149
|
+
PR_BASE=""
|
|
150
|
+
PR_LOOKUP=""
|
|
151
|
+
PR_LOOKUP_FULL=0
|
|
152
|
+
case "$BRANCH" in
|
|
153
|
+
dev|main|"") ;;
|
|
154
|
+
*)
|
|
155
|
+
if command -v gh >/dev/null 2>&1; then
|
|
156
|
+
# strip hook-injected GIT_DIR/GIT_WORK_TREE so gh resolves the repo from cwd (worktree-safe)
|
|
157
|
+
# push target owner/name from the URL in $2: a PR from that repo counts even when gh reports it cross-repository (a fork checkout)
|
|
158
|
+
PR_TARGET=${2%.git}
|
|
159
|
+
PR_TARGET_NAME=${PR_TARGET##*/}
|
|
160
|
+
PR_TARGET_OWNER=${PR_TARGET%/*}
|
|
161
|
+
PR_TARGET_OWNER=${PR_TARGET_OWNER##*[/:]}
|
|
162
|
+
case "$PR_TARGET_OWNER$PR_TARGET_NAME" in *[!A-Za-z0-9._-]*|"") PR_TARGET_OWNER=""; PR_TARGET_NAME="" ;; esac
|
|
163
|
+
# --limit 1000: fork PRs sharing the head name must not push the same-repo PR off the page; a full page with no match is an unknown, not "no PR"
|
|
164
|
+
PR_JQ='map(select((.isCrossRepository | not) or (.headRepositoryOwner.login == "'"$PR_TARGET_OWNER"'" and .headRepository.name == "'"$PR_TARGET_NAME"'"))) as $m | if ($m | length) > 0 then "\($m[0].number) \($m[0].baseRefName)" elif length >= 1000 then "FULL" else empty end'
|
|
165
|
+
if PR_INFO=$(env -u GIT_DIR -u GIT_WORK_TREE gh pr list --head "$BRANCH" --state open --limit 1000 --json number,baseRefName,isCrossRepository,headRepositoryOwner,headRepository --jq "$PR_JQ" < /dev/null 2>/dev/null); then
|
|
166
|
+
if [ "$PR_INFO" = "FULL" ]; then
|
|
167
|
+
PR_LOOKUP="1000 open PRs share this head branch name and none is from this repo"
|
|
168
|
+
PR_LOOKUP_FULL=1
|
|
169
|
+
PR_INFO=""
|
|
170
|
+
else
|
|
171
|
+
PR_LOOKUP=ok
|
|
172
|
+
fi
|
|
173
|
+
OPEN_PR=${PR_INFO%% *}
|
|
174
|
+
case "$PR_INFO" in *" "*) PR_BASE=${PR_INFO#* } ;; esac
|
|
175
|
+
else
|
|
176
|
+
PR_LOOKUP="gh pr list failed (offline, or gh not signed in)"
|
|
177
|
+
fi
|
|
178
|
+
else
|
|
179
|
+
PR_LOOKUP="gh is not installed"
|
|
180
|
+
fi
|
|
181
|
+
;;
|
|
182
|
+
esac
|
|
183
|
+
|
|
109
184
|
# CI-suppressor HEAD guard: blocks a push whose HEAD commit carries a [skip ci]-class
|
|
110
185
|
# token while the branch has an OPEN PR (that token silences GitHub's pull_request
|
|
111
186
|
# trigger). Covers manual pushes (rebase + force-push, post-close commits). No open PR
|
|
@@ -113,7 +188,7 @@ esac
|
|
|
113
188
|
# gh absent -> allow. `bkit ci skip-token` exits 0 when HEAD's message carries one of
|
|
114
189
|
# the tokens GitHub honours; bkit owns that list.
|
|
115
190
|
# Exception, the same one ship's merge gate makes: a push that adds only files on ship's
|
|
116
|
-
# `--scope=pr` allow-list (.bkit/workflows.md § `/bkit-ship` —
|
|
191
|
+
# `--scope=pr` allow-list (.bkit/workflows.md § `/bkit-ship` — 12 steps) on top of the
|
|
117
192
|
# head the remote already holds leaves nothing new for CI to test, so the PR's checks at
|
|
118
193
|
# that head still cover the code. `bkit ci bookkeeping-push` exits 0 for exactly that
|
|
119
194
|
# shape. A rewritten head (force-push) or any code file still blocks. The merge gate
|
|
@@ -122,9 +197,7 @@ case "$BRANCH" in
|
|
|
122
197
|
dev|main) ;;
|
|
123
198
|
*)
|
|
124
199
|
if pnpm -s bkit ci skip-token < /dev/null > /dev/null; then
|
|
125
|
-
if
|
|
126
|
-
# strip hook-injected GIT_DIR/GIT_WORK_TREE so gh resolves the repo from cwd (worktree-safe)
|
|
127
|
-
OPEN_PR=$(env -u GIT_DIR -u GIT_WORK_TREE gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number' 2>/dev/null || echo "")
|
|
200
|
+
if [ "$PR_LOOKUP" != "gh is not installed" ]; then
|
|
128
201
|
if [ -n "$OPEN_PR" ]; then
|
|
129
202
|
if [ -n "$PUSH_BRANCH_REMOTE_SHA" ] &&
|
|
130
203
|
pnpm -s bkit ci bookkeeping-push --from="$PUSH_BRANCH_REMOTE_SHA" < /dev/null > /dev/null; then
|
|
@@ -134,6 +207,10 @@ case "$BRANCH" in
|
|
|
134
207
|
echo "[pre-push] Add a clean trigger commit and re-push: git commit --allow-empty -m \"chore: trigger CI\" && git push" >&2
|
|
135
208
|
exit 1
|
|
136
209
|
fi
|
|
210
|
+
elif [ "$PR_LOOKUP_FULL" = "1" ]; then
|
|
211
|
+
echo "[pre-push] BLOCKED: HEAD on '$BRANCH' carries a CI-suppressing token and $PR_LOOKUP — an open PR for this branch cannot be ruled out." >&2
|
|
212
|
+
echo "[pre-push] Add a clean trigger commit and re-push: git commit --allow-empty -m \"chore: trigger CI\" && git push" >&2
|
|
213
|
+
exit 1
|
|
137
214
|
fi
|
|
138
215
|
else
|
|
139
216
|
echo "[pre-push] WARN: HEAD on '$BRANCH' carries a CI-suppressing token but gh is unavailable to check for an open PR; allowing. If a PR is open, ensure HEAD triggers CI." >&2
|
|
@@ -171,6 +248,46 @@ done
|
|
|
171
248
|
# block (seconds to ~30s, needing nothing the gates build) here too. Slow extras go below
|
|
172
249
|
# the gates.
|
|
173
250
|
#
|
|
251
|
+
# PR conflict: a feature branch whose open PR no longer merges into its base never starts CI,
|
|
252
|
+
# so the push stops here, before the gates. Fetches the base, then a trial merge of the pushed
|
|
253
|
+
# commit (`git merge-tree` exit 1 = conflicts; the work tree is untouched). A lookup, fetch or
|
|
254
|
+
# merge-tree that cannot answer warns and goes on: CI reports the conflict itself.
|
|
255
|
+
case "$BRANCH" in
|
|
256
|
+
dev|main|"") ;;
|
|
257
|
+
*)
|
|
258
|
+
if [ "$PR_LOOKUP" != "ok" ]; then
|
|
259
|
+
[ -z "$PR_LOOKUP" ] || echo "[pre-push] WARN: PR conflict check skipped — $PR_LOOKUP, so whether '$BRANCH' has an open PR that conflicts is unknown." >&2
|
|
260
|
+
elif [ -n "$OPEN_PR" ] && [ -n "$PR_BASE" ] && [ -n "$PUSH_BRANCH_SHA" ]; then
|
|
261
|
+
if [ "${BKIT_PR_CONFLICT_CHECK:-}" = "false" ]; then
|
|
262
|
+
echo "[pre-push] PR conflict check off (BKIT_PR_CONFLICT_CHECK=false)." >&2
|
|
263
|
+
# a shallow clone has no shared history with the base: the fetch would download all of it and merge-tree still refuse
|
|
264
|
+
elif [ "$(git rev-parse --is-shallow-repository 2>/dev/null)" = "true" ]; then
|
|
265
|
+
echo "[pre-push] WARN: PR conflict check skipped — shallow clone; run git fetch --unshallow to enable it." >&2
|
|
266
|
+
# explicit refspec: a single-branch clone's `git fetch origin <base>` would leave no origin/<base>
|
|
267
|
+
elif git fetch --quiet origin "+refs/heads/$PR_BASE:refs/remotes/origin/$PR_BASE" < /dev/null > /dev/null 2>&1; then
|
|
268
|
+
PR_MERGE_RC=0
|
|
269
|
+
# empty attribute source: GitHub applies no merge=union driver, so neither does this trial merge
|
|
270
|
+
PR_MERGE_OUT=$(git --attr-source="$(git hash-object -t tree /dev/null)" merge-tree --write-tree --name-only "refs/remotes/origin/$PR_BASE" "$PUSH_BRANCH_SHA" < /dev/null 2>/dev/null) || PR_MERGE_RC=$?
|
|
271
|
+
# exit 1 is a conflict only when the first output line is the result tree's OID
|
|
272
|
+
case "$PR_MERGE_OUT" in
|
|
273
|
+
[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]*) ;;
|
|
274
|
+
*) [ "$PR_MERGE_RC" != "1" ] || PR_MERGE_RC=2 ;;
|
|
275
|
+
esac
|
|
276
|
+
if [ "$PR_MERGE_RC" = "1" ]; then
|
|
277
|
+
echo "[pre-push] BLOCKED: PR #$OPEN_PR does not merge into '$PR_BASE', so CI would not start. Conflicting files:" >&2
|
|
278
|
+
echo "$PR_MERGE_OUT" | sed '1d;/^$/,$d;s/^/[pre-push] /' >&2
|
|
279
|
+
echo "[pre-push] Fix: git fetch origin $PR_BASE && git merge origin/$PR_BASE (or rebase), resolve, commit, push again." >&2
|
|
280
|
+
exit 1
|
|
281
|
+
elif [ "$PR_MERGE_RC" != "0" ]; then
|
|
282
|
+
echo "[pre-push] WARN: PR conflict check skipped — git merge-tree failed (exit $PR_MERGE_RC)." >&2
|
|
283
|
+
fi
|
|
284
|
+
else
|
|
285
|
+
echo "[pre-push] WARN: PR conflict check skipped — could not fetch '$PR_BASE' from origin." >&2
|
|
286
|
+
fi
|
|
287
|
+
fi
|
|
288
|
+
;;
|
|
289
|
+
esac
|
|
290
|
+
|
|
174
291
|
# bkit mirror-drift gate — fails if `.agents/*` was edited without `bkit install`
|
|
175
292
|
# regenerating the `.claude/*`/`.cursor/*` mirrors (same check CI runs).
|
|
176
293
|
# Outside the gate scripts: it validates the bkit install, not your source.
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
# Serena — MCP server in cloud sessions
|
|
5
5
|
|
|
6
|
-
Fits: repos that wire the Serena MCP server (`.bkit/templates.md` § Serena).
|
|
6
|
+
Fits: repos that wire the Serena MCP server (`.bkit/templates.md` § Serena). This template has no fetch block. A provision block on its own installs the `serena` binary in Claude cloud sessions, so the MCP server starts there too, and the `mcp-servers` entry lets every host run its tools without a prompt.
|
|
7
7
|
|
|
8
8
|
- Secret: none.
|
|
9
9
|
- CLI: `uv`, which is pre-installed on the Claude cloud image. The setup script runs as root, so the block pins uv's tool venv and bin dir to world-readable paths. Under root's `$HOME` (mode 0700), the session user could not run the binary.
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
> Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/architecture.md`, fill it in, then delete this introduction.
|
|
2
|
+
>
|
|
3
|
+
> **Fill these first:** `docs/technology.md`.
|
|
4
|
+
>
|
|
5
|
+
> **Finish against:** none.
|
|
6
|
+
>
|
|
7
|
+
> **Where the facts come from:** the repository's top-level folders and package manifests, the build and deploy configuration, the CI configuration and the infrastructure files.
|
|
8
|
+
>
|
|
9
|
+
> **Fill in:**
|
|
10
|
+
>
|
|
11
|
+
> 1. Copy this starter to `docs/architecture.md`.
|
|
12
|
+
> 2. List the top-level source folders and the package manifests, and group them into runtimes: parts that run in one process or one place.
|
|
13
|
+
> 3. Draw `## System context` as one chart with a `subgraph` per runtime, and name each runtime and external system as the tables below name them.
|
|
14
|
+
> 4. Fill `## Containers` with one row per runtime and what it owns.
|
|
15
|
+
> 5. Fill `## Package boundaries` with who may call whom, and name the check that enforces each boundary.
|
|
16
|
+
> 6. Fill `## File placement` with one row per kind of file the repository holds. Agents place every new file by this table.
|
|
17
|
+
> 7. Fill `## Environments` with where each part runs. Leave each environment's branch, URL and release trigger to `docs/deployments.md`.
|
|
18
|
+
> 8. Record unresolved facts under `## Open questions`.
|
|
19
|
+
> 9. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/architecture.md` | ● | ● | ● | ○ | ○ | How the system is built and where it runs: runtimes, package boundaries, file placement and environments. |
|
|
20
|
+
> 10. Check the document against each completion check, then delete this introduction.
|
|
21
|
+
>
|
|
22
|
+
> **If it does not apply:** every project has a structure. Write `Not applicable: {reason}` under a section that does not apply, such as `## Package boundaries` for a single-package repository.
|
|
23
|
+
>
|
|
24
|
+
> **Completion checks:**
|
|
25
|
+
>
|
|
26
|
+
> - Exactly one Mermaid chart, and it renders in a Mermaid-capable viewer.
|
|
27
|
+
> - Every runtime in the chart has a row in `## Containers`.
|
|
28
|
+
> - Every top-level source folder appears in a row of `## File placement`.
|
|
29
|
+
> - Every environment names where it runs, with no branch, URL or release trigger.
|
|
30
|
+
> - No example row remains.
|
|
31
|
+
|
|
32
|
+
# Architecture
|
|
33
|
+
|
|
34
|
+
> [!CAUTION]
|
|
35
|
+
> **Purpose:** How the system is built and where it runs: runtimes, package boundaries, file placement and environments.
|
|
36
|
+
>
|
|
37
|
+
> **Rules:**
|
|
38
|
+
>
|
|
39
|
+
> - Follow `.bkit/authoring.md` § Docs when you edit this file.
|
|
40
|
+
> - Hold topology and boundaries only. Library lists and operational rules go in the domain docs.
|
|
41
|
+
> - Cite the repository evidence for each fact: a path, a configuration file or a CI job.
|
|
42
|
+
>
|
|
43
|
+
> **Not here:** The chosen libraries go in `docs/technology.md`. Each environment's branch, URL and release trigger go in `docs/deployments.md` § Environments. Purpose-based responsibilities go in `docs/components.md`.
|
|
44
|
+
>
|
|
45
|
+
> **Update when:** A package, runtime or kind of file is added or removed, a boundary shifts, or an environment is added or removed.
|
|
46
|
+
|
|
47
|
+
## System context
|
|
48
|
+
|
|
49
|
+
[The runtimes of the system and the external systems each one talks to. The arrows show which part calls which.]
|
|
50
|
+
|
|
51
|
+
```mermaid
|
|
52
|
+
flowchart LR
|
|
53
|
+
subgraph CLIENT["Client runtime"]
|
|
54
|
+
UI["User interface"]
|
|
55
|
+
end
|
|
56
|
+
subgraph SERVER["Server runtime"]
|
|
57
|
+
API["Report service"]
|
|
58
|
+
end
|
|
59
|
+
STORE["Record storage"]
|
|
60
|
+
UI --> API
|
|
61
|
+
API --> STORE
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Containers
|
|
65
|
+
|
|
66
|
+
<!-- prettier-ignore -->
|
|
67
|
+
| Runtime | Owns | Talks to |
|
|
68
|
+
| --- | --- | --- |
|
|
69
|
+
| [Runtime name] | [What it is responsible for.] | [Other runtimes and external systems.] |
|
|
70
|
+
| [e.g., Report service] | Report preparation and saving. | The user interface and record storage. |
|
|
71
|
+
|
|
72
|
+
## Package boundaries
|
|
73
|
+
|
|
74
|
+
<!-- prettier-ignore -->
|
|
75
|
+
| Package or folder | May call | Must not call | Enforced by |
|
|
76
|
+
| --- | --- | --- | --- |
|
|
77
|
+
| [Package or folder] | [What it may depend on.] | [What it must not depend on.] | [Check or review step.] |
|
|
78
|
+
| [e.g., Report service] | The shared library. | The user interface. | The import-boundary lint rule. |
|
|
79
|
+
|
|
80
|
+
## File placement
|
|
81
|
+
|
|
82
|
+
<!-- prettier-ignore -->
|
|
83
|
+
| Kind of file | Goes in | Naming |
|
|
84
|
+
| --- | --- | --- |
|
|
85
|
+
| [Kind of file] | [Folder.] | [Name pattern.] |
|
|
86
|
+
| [e.g., Unit test] | Next to the file it tests. | The source file's name with a test suffix. |
|
|
87
|
+
|
|
88
|
+
## Environments
|
|
89
|
+
|
|
90
|
+
<!-- prettier-ignore -->
|
|
91
|
+
| Environment | Hosting | Data store | Who uses it |
|
|
92
|
+
| --- | --- | --- | --- |
|
|
93
|
+
| [Environment] | [Where the parts run.] | [Which store it uses.] | [Who uses it.] |
|
|
94
|
+
| [e.g., Production] | A managed hosting platform. | The production database. | End users. |
|
|
95
|
+
|
|
96
|
+
## Open questions
|
|
97
|
+
|
|
98
|
+
[Each unresolved fact, who can answer it and which section it affects.]
|
|
@@ -1,6 +1,21 @@
|
|
|
1
|
-
>
|
|
1
|
+
> Generated document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/capabilities.md`, build it with the command below, then delete this introduction.
|
|
2
2
|
>
|
|
3
|
-
>
|
|
3
|
+
> **Fill these first:** `docs/deployments.md`.
|
|
4
|
+
>
|
|
5
|
+
> **Prerequisites:** the code exists, and the graphify templates are adopted as `.bkit/templates.md` § graphify — map describes.
|
|
6
|
+
>
|
|
7
|
+
> **Build it:**
|
|
8
|
+
>
|
|
9
|
+
> 1. Copy this starter to `docs/capabilities.md`.
|
|
10
|
+
> 2. Add each capability to `scripts/graphify/bkit-graph-drift-rules.json`. That file is the source of truth, and it stays hand-maintained.
|
|
11
|
+
> 3. Run `pnpm bkit:graph:rollup` to build the register from the working tree. Run it while you edit, when you want to see the result before staging.
|
|
12
|
+
> 4. Run `pnpm bkit:graph:refresh` to build the register from the staged files in a throwaway checkout. Run it before a commit, so the committed file matches the committed code.
|
|
13
|
+
> 5. Edit only the text outside the `graphify:start` and `graphify:end` marker lines. Each run rewrites everything between them.
|
|
14
|
+
> 6. Record unresolved facts under `## Open questions`.
|
|
15
|
+
> 7. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/capabilities.md` | ● | ● | ● | — | ○ | One row per capability, with its owner module, the literal marker that finds every use of it, and whether anything bypasses the owner. |
|
|
16
|
+
> 8. Check the document against each completion check, then delete this introduction.
|
|
17
|
+
>
|
|
18
|
+
> **Completion checks:** the register has a row for every capability in `scripts/graphify/bkit-graph-drift-rules.json`, every responsibility in `docs/components.md` that owns a capability appears in both documents, and the text between the two marker lines no longer reads `Not built`.
|
|
4
19
|
|
|
5
20
|
# Capabilities
|
|
6
21
|
|
|
@@ -9,41 +24,30 @@
|
|
|
9
24
|
>
|
|
10
25
|
> **Rules:**
|
|
11
26
|
>
|
|
12
|
-
> -
|
|
27
|
+
> - Follow `.bkit/authoring.md` § Docs when you edit this file.
|
|
28
|
+
> - `pnpm bkit:graph:rollup` and `pnpm bkit:graph:refresh` rewrite everything between the `graphify:start` and `graphify:end` marker lines. Never edit between them, and keep exactly one of each.
|
|
13
29
|
> - The source of truth is `scripts/graphify/bkit-graph-drift-rules.json`. Each status is derived from the tree, never typed in.
|
|
30
|
+
> - To add a capability, add a rule there: capability, lane, owner module and one literal marker.
|
|
14
31
|
> - Markers are literal, never regex. A regex metacharacter in a marker matches nothing, and the row then reads as a clean result.
|
|
15
|
-
> -
|
|
16
|
-
> - Optional `
|
|
32
|
+
> - Match the mechanism, not the name, because a marker such as `createClient(` misses an owner that imports it under another name.
|
|
33
|
+
> - Optional `scope`: path prefixes that narrow the tree scanned, for a marker that means different things per package.
|
|
34
|
+
> - Optional `surface`: `product` (default), `tests` or `all`. `tests` is every `e2e/` folder and every `.test.` or `.spec.` file, and `product` is every other file.
|
|
17
35
|
> - Optional `budgets`: the exact non-owner site count allowed per scope prefix. Measured = declared → `budgeted`.
|
|
18
|
-
> -
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
| Status | Meaning | Action |
|
|
24
|
-
| --- | --- | --- |
|
|
25
|
-
| `split` | Two or more implementations, no single owner | Centralise, or budget it and say why in `note` |
|
|
26
|
-
| `bypassed` | Owner exists, some callers skip it | Repoint the callers, or budget them |
|
|
27
|
-
| `dead` | A client fetches a path nothing serves | Check the call site |
|
|
28
|
-
| `gap` | No owner file yet | Name the owner before the first caller |
|
|
29
|
-
| `budgeted` | A `split` or `bypassed` whose site count matches the declared budget | None, until a site appears or disappears |
|
|
30
|
-
| `one` | Every caller goes through the owner | None |
|
|
36
|
+
> - The generator reads the Overrides block before it writes. A malformed block aborts the run.
|
|
37
|
+
>
|
|
38
|
+
> **Not here:** The purpose-based view of responsibilities goes in `docs/components.md`. Implementation boundaries and deployment topology go in `docs/architecture.md`. Issue state stays in the tracker.
|
|
39
|
+
>
|
|
40
|
+
> **Update when:** A rule in `scripts/graphify/bkit-graph-drift-rules.json` is added, changed or removed, or a code change moves a status. Run `pnpm bkit:graph:refresh` in the same change.
|
|
31
41
|
|
|
32
|
-
|
|
42
|
+
<!-- graphify:start -->
|
|
33
43
|
|
|
34
44
|
Not built. Run `pnpm bkit:graph:rollup`.
|
|
35
45
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
Not scanned.
|
|
39
|
-
|
|
40
|
-
## Import-time side effects
|
|
41
|
-
|
|
42
|
-
Not scanned.
|
|
46
|
+
<!-- graphify:end -->
|
|
43
47
|
|
|
44
48
|
## Overrides
|
|
45
49
|
|
|
46
|
-
|
|
50
|
+
Use this block to rename a node, hide a node or an edge, pin a note, or force nodes into a named group. Each `hide_nodes` entry needs a one-line reason in `hide_nodes_why`.
|
|
47
51
|
|
|
48
52
|
<!-- overrides:start -->
|
|
49
53
|
|
|
@@ -60,14 +64,6 @@ This is the only hand-maintained region. Use it to rename a node, hide a node or
|
|
|
60
64
|
|
|
61
65
|
<!-- overrides:end -->
|
|
62
66
|
|
|
63
|
-
##
|
|
64
|
-
|
|
65
|
-
No route layer yet. Run `pnpm bkit:graph:rollup`.
|
|
66
|
-
|
|
67
|
-
## Architecture — packages
|
|
68
|
-
|
|
69
|
-
Filled by `pnpm bkit:graph:rollup`.
|
|
70
|
-
|
|
71
|
-
## Architecture — modules
|
|
67
|
+
## Open questions
|
|
72
68
|
|
|
73
|
-
|
|
69
|
+
[Each unresolved fact, who can answer it and which section it affects.]
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
> Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/components.md`, fill it in, then delete this introduction.
|
|
2
|
+
>
|
|
3
|
+
> **Fill these first:** `docs/idea.md`.
|
|
4
|
+
>
|
|
5
|
+
> **Finish against:** none.
|
|
6
|
+
>
|
|
7
|
+
> **Where the facts come from:** `docs/idea.md`, the repository's README, any approved specification and, once code exists, its main entry points.
|
|
8
|
+
>
|
|
9
|
+
> **Fill in:**
|
|
10
|
+
>
|
|
11
|
+
> 1. Copy this starter to `docs/components.md`.
|
|
12
|
+
> 2. Read `docs/idea.md`, the README and any approved specification.
|
|
13
|
+
> 3. **If** an implementation exists → check its main entry points and representative behavior against those sources before describing anything as current.
|
|
14
|
+
> 4. **If** no implementation exists → use the approved specification as the source for a planned view.
|
|
15
|
+
> 5. **If** neither source establishes the purpose, intended users or main journey → ask the owner for that missing context before filling the affected sections.
|
|
16
|
+
> 6. Select components by distinct responsibilities or outcomes, including supporting work the main journeys depend on. Code that serves one purpose can share a component; separate a responsibility when it has its own outcome or a meaningful handoff.
|
|
17
|
+
> 7. Replace the bracketed fields and example rows with the project's facts, keeping the rules box.
|
|
18
|
+
> 8. Fill `## Constraints` from `docs/idea.md`, the README, any approved specification and the owner's answers, and name the source of each row.
|
|
19
|
+
> 9. Record unresolved facts under `## Open questions`, separate from current behavior and approved plans.
|
|
20
|
+
> 10. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/components.md` | ○ | ● | ○ | ○ | ○ | A purpose-based view of what the repository does, its major responsibilities and how they work together, readable without inspecting the code. |
|
|
21
|
+
> 11. Check the document against each completion check, then delete this introduction.
|
|
22
|
+
>
|
|
23
|
+
> **If it does not apply:** every repository has components. Write `Not applicable: {reason}` under a section that does not apply, such as Delivery and ownership for a repository without distinct distributed content. Core, Shared and Templates are examples, not required categories.
|
|
24
|
+
>
|
|
25
|
+
> **Completion checks:**
|
|
26
|
+
>
|
|
27
|
+
> - The opening identifies the users, problem, result and main limits without requiring code knowledge.
|
|
28
|
+
> - Each component has a purpose, a responsibility and a named collaborator or external actor.
|
|
29
|
+
> - Each main journey leads from an input to an outcome, with a failure or review path where relevant.
|
|
30
|
+
> - Exactly one Mermaid chart uses names consistent with the tables and explains what its arrows mean.
|
|
31
|
+
> - The chart renders in a Mermaid-capable viewer.
|
|
32
|
+
> - Every claimed current responsibility is supported by the implementation or project evidence; planned responsibilities and unknowns are labelled separately.
|
|
33
|
+
> - Every constraint names its source: `docs/idea.md`, the README, an approved specification or the owner's answer.
|
|
34
|
+
> - References link to existing documents; missing optional views are marked as unavailable rather than linked to nonexistent files.
|
|
35
|
+
> - Implementation detail stays in its canonical document rather than being copied into this overview.
|
|
36
|
+
> - No instructional placeholders or unrelated example content remain.
|
|
37
|
+
|
|
38
|
+
# Components
|
|
39
|
+
|
|
40
|
+
> [!CAUTION]
|
|
41
|
+
> **Purpose:** A purpose-based view of what the repository does, its major responsibilities and how they work together, readable without inspecting the code.
|
|
42
|
+
>
|
|
43
|
+
> **Rules:**
|
|
44
|
+
>
|
|
45
|
+
> - Follow `.bkit/authoring.md` § Docs when you edit this file.
|
|
46
|
+
> - Group components by the purpose they serve, independently of files, packages and deployment units.
|
|
47
|
+
> - Describe each component's responsibility and its relationships in plain language.
|
|
48
|
+
> - Distinguish current behavior from agreed scope, proposals and later candidates.
|
|
49
|
+
> - Components and capabilities may have different names, counts and boundaries.
|
|
50
|
+
>
|
|
51
|
+
> **Not here:** Implementation boundaries and deployment topology go in `docs/architecture.md`. Implementation ownership and drift go in `docs/capabilities.md` when present. Issue state and delivery plans stay in the tracker.
|
|
52
|
+
>
|
|
53
|
+
> **Update when:** The repository's purpose, responsibilities, constraints or main journeys change.
|
|
54
|
+
|
|
55
|
+
## Repository purpose
|
|
56
|
+
|
|
57
|
+
[The intended users, problem, result and main limits of the repository.]
|
|
58
|
+
|
|
59
|
+
[The core concepts expressed as responsibilities, with links to the existing product guide or specification for detail.]
|
|
60
|
+
|
|
61
|
+
## Constraints
|
|
62
|
+
|
|
63
|
+
[The platforms, offline behavior, live-update needs, scale and hard external requirements the repository must meet.]
|
|
64
|
+
|
|
65
|
+
<!-- prettier-ignore -->
|
|
66
|
+
| Constraint | What it requires | Source |
|
|
67
|
+
| --- | --- | --- |
|
|
68
|
+
| [Constraint] | [What it requires of the repository.] | [The `docs/idea.md` passage, README section, specification or owner's answer that states it.] |
|
|
69
|
+
| [e.g., Works offline] | Reports open and save without a network connection. | The "Field use" notes in `docs/idea.md`. |
|
|
70
|
+
|
|
71
|
+
## Primary workflows
|
|
72
|
+
|
|
73
|
+
[The main workflows, including any optional stages, direct entry points and recovery paths.]
|
|
74
|
+
|
|
75
|
+
<!-- prettier-ignore -->
|
|
76
|
+
| Workflow | Purpose | Starts with | Produces |
|
|
77
|
+
| --- | --- | --- | --- |
|
|
78
|
+
| [User-recognizable workflow] | [Outcome it is responsible for.] | [Input or trigger.] | [Result or handoff.] |
|
|
79
|
+
| [e.g., Produce a report] | Turn selected records into a readable summary. | A user's request and selected records. | A saved report ready to read. |
|
|
80
|
+
|
|
81
|
+
## Delivery and ownership
|
|
82
|
+
|
|
83
|
+
[The distinct kinds of content the repository distributes, their purposes and who maintains the installed or adopted result.]
|
|
84
|
+
|
|
85
|
+
<!-- prettier-ignore -->
|
|
86
|
+
| Part | Purpose | What it supplies | Maintained by |
|
|
87
|
+
| --- | --- | --- | --- |
|
|
88
|
+
| [Project-specific part] | [Outcome served.] | [Responsibilities grouped by purpose.] | [Owner of the delivered result.] |
|
|
89
|
+
| [e.g., Optional report layouts] | Adapt reports to an organization's needs. | Layout examples copied into the project. | The adopting project maintains its copies. |
|
|
90
|
+
|
|
91
|
+
## Component map
|
|
92
|
+
|
|
93
|
+
[One chart of the main responsibilities, workflows and supporting relationships, including delivery roles or supported hosts and providers where central to the product.]
|
|
94
|
+
|
|
95
|
+
[What the arrows mean and whether they show a sequence, collaboration or dependency.]
|
|
96
|
+
|
|
97
|
+
```mermaid
|
|
98
|
+
flowchart LR
|
|
99
|
+
REQUEST["Request a report"] --> PREPARE["Report preparation"]
|
|
100
|
+
PREPARE --> READ["Read the report"]
|
|
101
|
+
RECORDS["Record storage"] --> PREPARE
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## Component breakdown
|
|
105
|
+
|
|
106
|
+
<!-- prettier-ignore -->
|
|
107
|
+
| Purpose | Component | Responsibility | Works with |
|
|
108
|
+
| --- | --- | --- | --- |
|
|
109
|
+
| [Outcome served] | [Plain-language name] | [What it does and produces, without requiring code knowledge.] | [Other components or external actors, and what they exchange.] |
|
|
110
|
+
| [e.g., Produce a report] | Report preparation | Validate selected records and turn them into a saved summary. | Record storage supplies the inputs; the reader receives the report. |
|
|
111
|
+
|
|
112
|
+
## Main journeys
|
|
113
|
+
|
|
114
|
+
### [User goal]
|
|
115
|
+
|
|
116
|
+
1. [Who starts the journey and what they provide.]
|
|
117
|
+
2. [Which responsibilities collaborate to produce the result.]
|
|
118
|
+
3. [What the user receives, including any review or recovery path.]
|
|
119
|
+
|
|
120
|
+
## Shared foundations
|
|
121
|
+
|
|
122
|
+
[Responsibilities used across the main components, such as permissions, persistence, configuration and operational evidence, with links to their canonical documents.]
|
|
123
|
+
|
|
124
|
+
## Scope
|
|
125
|
+
|
|
126
|
+
[Whether this is a current or planned view, with agreed scope, proposals, later candidates and open questions distinguished. Links to the existing homes of delivery plans and issue state.]
|
|
127
|
+
|
|
128
|
+
## Related views
|
|
129
|
+
|
|
130
|
+
<!-- prettier-ignore -->
|
|
131
|
+
| View | Question it answers |
|
|
132
|
+
| --- | --- |
|
|
133
|
+
| `docs/architecture.md`, when present | How is the system implemented and deployed? |
|
|
134
|
+
| `docs/capabilities.md`, when present | Where is a capability implemented, and do callers use its owner? |
|
|
135
|
+
| `floorplan/`, when present | How can I explore the code's files, connections and guided flows? |
|
|
136
|
+
| [e.g., Product guide] | What does the product do, for whom? |
|
|
137
|
+
|
|
138
|
+
[Links to the available views above and the repository's product guide or specification. Missing views identified as unavailable.]
|
|
139
|
+
|
|
140
|
+
## Open questions
|
|
141
|
+
|
|
142
|
+
[Each unresolved fact, who can answer it and which section it affects.]
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
> Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/data-schema.md`, fill it in, then delete this introduction.
|
|
2
|
+
>
|
|
3
|
+
> **Fill these first:** `docs/security.md`.
|
|
4
|
+
>
|
|
5
|
+
> **Finish against:** none.
|
|
6
|
+
>
|
|
7
|
+
> **Where the facts come from:** the migration files, the schema definition or model files, the access-policy definitions, and a generated schema export when the database tool can produce one.
|
|
8
|
+
>
|
|
9
|
+
> **Fill in:**
|
|
10
|
+
>
|
|
11
|
+
> 1. Copy this starter to `docs/data-schema.md`.
|
|
12
|
+
> 2. Fill `## Overview` with the stores the project uses, and draw each table's keys and relationships in the chart.
|
|
13
|
+
> 3. Copy the `## [Table name]` section once per table, and fill its fields, indices, access policies and `Pending` list. Read the personal-data fields from `docs/security.md` § PII, and add each one's table and field to the "Where stored" column there.
|
|
14
|
+
> 4. Fill `## Functions` with each stored function and trigger.
|
|
15
|
+
> 5. Record unresolved facts under `## Open questions`.
|
|
16
|
+
> 6. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/data-schema.md` | ○ | ○ | ● | ○ | ○ | The active production schema: tables, fields, access policies, indices, functions and triggers. |
|
|
17
|
+
> 7. Check the document against each completion check, then delete this introduction.
|
|
18
|
+
>
|
|
19
|
+
> **If it does not apply:** write `Not applicable: no persistent store` under `## Overview` and remove the other sections except `## Open questions`.
|
|
20
|
+
>
|
|
21
|
+
> **Completion checks:**
|
|
22
|
+
>
|
|
23
|
+
> - Every table in the migration files has a section.
|
|
24
|
+
> - Every key and relationship in the chart matches a field in a table section.
|
|
25
|
+
> - Every personal-data field in `docs/security.md` § PII appears in a table section.
|
|
26
|
+
> - No example row remains.
|
|
27
|
+
|
|
28
|
+
# Data Schema
|
|
29
|
+
|
|
30
|
+
> [!CAUTION]
|
|
31
|
+
> **Purpose:** The active production schema: tables, fields, access policies, indices, functions and triggers.
|
|
32
|
+
>
|
|
33
|
+
> **Rules:**
|
|
34
|
+
>
|
|
35
|
+
> - Follow `.bkit/authoring.md` § Docs when you edit this file.
|
|
36
|
+
> - Give each table one section, holding a `Field | Type | Unique | Notes` table, `Indices` and `Pending`.
|
|
37
|
+
> - `Pending` means a change a migration on an open branch will make and the production schema does not yet have. Move it into the table when the migration deploys.
|
|
38
|
+
> - When the database tool generates a schema export, link it instead of copying it here.
|
|
39
|
+
> - For a field whose existence is a decision, link its ADR in `decisions.jsonl`, and do not restate the rationale.
|
|
40
|
+
>
|
|
41
|
+
> **Not here:** How personal data is protected goes in `docs/security.md` § PII. Migration order and deploy steps go in `docs/deployments.md` § Applying migrations at deploy time. Test fixtures go in `docs/testing.md` § Test data.
|
|
42
|
+
>
|
|
43
|
+
> **Update when:** A table, field, index, access policy, function or trigger is added, changed or removed in production.
|
|
44
|
+
|
|
45
|
+
## Overview
|
|
46
|
+
|
|
47
|
+
[The stores the project uses, and how its tables relate.]
|
|
48
|
+
|
|
49
|
+
```mermaid
|
|
50
|
+
erDiagram
|
|
51
|
+
ACCOUNT ||--o{ REPORT : owns
|
|
52
|
+
ACCOUNT {
|
|
53
|
+
uuid id PK
|
|
54
|
+
}
|
|
55
|
+
REPORT {
|
|
56
|
+
uuid id PK
|
|
57
|
+
uuid account_id FK
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## [Table name]
|
|
62
|
+
|
|
63
|
+
[What the table holds.]
|
|
64
|
+
|
|
65
|
+
<!-- prettier-ignore -->
|
|
66
|
+
| Field | Type | Unique | Notes |
|
|
67
|
+
| --- | --- | --- | --- |
|
|
68
|
+
| [Field name] | [Type.] | [Yes or no.] | [Default, constraint or link to a decision.] |
|
|
69
|
+
| [e.g., id] | uuid | Yes | Primary key. |
|
|
70
|
+
|
|
71
|
+
**Indices:** [Each index and the query it serves.]
|
|
72
|
+
|
|
73
|
+
**Access policies:** [Who may read and write each row.]
|
|
74
|
+
|
|
75
|
+
**Pending:** [Changes a migration on an open branch will make, or none.]
|
|
76
|
+
|
|
77
|
+
## Functions
|
|
78
|
+
|
|
79
|
+
<!-- prettier-ignore -->
|
|
80
|
+
| Function or trigger | Fires on | Does |
|
|
81
|
+
| --- | --- | --- |
|
|
82
|
+
| [Name] | [Call or event.] | [What it does.] |
|
|
83
|
+
| [e.g., set_updated_at] | Update of a report row. | Sets the update time. |
|
|
84
|
+
|
|
85
|
+
## Open questions
|
|
86
|
+
|
|
87
|
+
[Each unresolved fact, who can answer it and which section it affects.]
|