@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
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
> Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/noise.md`, fill it in, then delete this introduction.
|
|
2
|
+
>
|
|
3
|
+
> **Fill these first:** `docs/observability.md`.
|
|
4
|
+
>
|
|
5
|
+
> **Finish against:** none.
|
|
6
|
+
>
|
|
7
|
+
> **Where the facts come from:** the log-level changes in the code, the error tracker's archived and muted issues, and the alert rules whose thresholds were raised.
|
|
8
|
+
>
|
|
9
|
+
> **Fill in:**
|
|
10
|
+
>
|
|
11
|
+
> 1. Copy this starter to `docs/noise.md`. The table starts empty, because the file is append-only.
|
|
12
|
+
> 2. Add one row for each signal already downgraded: a log-level reduction, an archived or muted error-tracker issue or a raised alert threshold.
|
|
13
|
+
> 3. Add a row in the same change as every later downgrade, before the signal goes quiet.
|
|
14
|
+
> 4. Record unresolved facts under `## Open questions`.
|
|
15
|
+
> 5. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/noise.md` | — | — | ○ | ● | ○ | Intentional signal downgrades: log levels, error-tracker archives and mutes, and alert thresholds, each with its trigger and reason. |
|
|
16
|
+
> 6. Check the document against each completion check, then delete this introduction.
|
|
17
|
+
>
|
|
18
|
+
> **If it does not apply:** a project with no downgraded signal keeps the empty table.
|
|
19
|
+
>
|
|
20
|
+
> **Completion checks:**
|
|
21
|
+
>
|
|
22
|
+
> - Every downgraded signal has one row with a trigger and a reason it is safe.
|
|
23
|
+
> - Every row names the signal in the way `docs/observability.md` § Signals names it.
|
|
24
|
+
|
|
25
|
+
# Noise
|
|
26
|
+
|
|
27
|
+
> [!CAUTION]
|
|
28
|
+
> **Purpose:** Intentional signal downgrades: log levels, error-tracker archives and mutes, and alert thresholds, each with its trigger and reason.
|
|
29
|
+
>
|
|
30
|
+
> **Rules:**
|
|
31
|
+
>
|
|
32
|
+
> - Follow `.bkit/authoring.md` § Docs when you edit this file.
|
|
33
|
+
> - This file is append-only.
|
|
34
|
+
> - Add one row per downgraded file or line, archived issue or raised threshold.
|
|
35
|
+
> - Downgrade a signal only when its trigger is known and expected.
|
|
36
|
+
> - Record the trigger, not just the verdict.
|
|
37
|
+
> - Never silence a signal at its source. Log it at a lower level instead.
|
|
38
|
+
> - Archive or mute an issue only when it is recorded here.
|
|
39
|
+
>
|
|
40
|
+
> **Not here:** The signals themselves and the alerts go in `docs/observability.md`.
|
|
41
|
+
>
|
|
42
|
+
> **Update when:** A signal is downgraded, or a recheck condition in a row is met. Add a row for either, and leave every earlier row as it is.
|
|
43
|
+
|
|
44
|
+
## Downgrades
|
|
45
|
+
|
|
46
|
+
[One row per downgraded signal, added at the bottom.]
|
|
47
|
+
|
|
48
|
+
<!-- prettier-ignore -->
|
|
49
|
+
| Date | Signal | Where | Change | Trigger | Why it is safe | Recheck when |
|
|
50
|
+
| --- | --- | --- | --- | --- | --- | --- |
|
|
51
|
+
|
|
52
|
+
## Open questions
|
|
53
|
+
|
|
54
|
+
[Each unresolved fact, who can answer it and which section it affects.]
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
> Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/observability.md`, fill it in, then delete this introduction.
|
|
2
|
+
>
|
|
3
|
+
> **Fill these first:** `docs/architecture.md`.
|
|
4
|
+
>
|
|
5
|
+
> **Finish against:** `docs/security.md` for `## Log format`, which is checked against the personal data that doc lists, so none of it gets logged.
|
|
6
|
+
>
|
|
7
|
+
> **Where the facts come from:** the logger module and its configuration, the code that emits named log events, spans and metrics, the error-tracker and log-drain configuration, and the alert rules.
|
|
8
|
+
>
|
|
9
|
+
> **Fill in:**
|
|
10
|
+
>
|
|
11
|
+
> 1. Copy this starter to `docs/observability.md`.
|
|
12
|
+
> 2. Redraw `## Signal pipeline` as the path a signal takes from the application to the people who act on it.
|
|
13
|
+
> 3. Fill `## Log format` by naming the logger module and the call every log line goes through, then the fields each line carries.
|
|
14
|
+
> 4. Fill `## Signals` with one row per named log event, span, metric or audit record that an alert, a test, a `docs/noise.md` row or another doc relies on. Leave out ordinary log lines.
|
|
15
|
+
> 5. Fill `## Correlation` with the identifier that ties one request together across runtimes, and where it is set.
|
|
16
|
+
> 6. Fill `## Error tracking` with the tool that collects errors and how an error reaches it.
|
|
17
|
+
> 7. Fill `## Alerts` with one row per alert: what fires it, the threshold and who is told.
|
|
18
|
+
> 8. Fill `## Where to look` with where to read each kind of signal when something fails.
|
|
19
|
+
> 9. Record unresolved facts under `## Open questions`.
|
|
20
|
+
> 10. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/observability.md` | ○ | ○ | ● | ● | ○ | Logging architecture, correlation tracing, telemetry pipelines, error tracking and alerts. |
|
|
21
|
+
> 11. Check the document against each completion check, then delete this introduction.
|
|
22
|
+
>
|
|
23
|
+
> **If it does not apply:** write `Not applicable: {reason}` under a section that does not apply, such as `## Alerts` for a project with none.
|
|
24
|
+
>
|
|
25
|
+
> **Completion checks:**
|
|
26
|
+
>
|
|
27
|
+
> - The chart names every place a signal is sent to.
|
|
28
|
+
> - `## Log format` names a logger module that exists in the code.
|
|
29
|
+
> - Every signal an alert reads has a row in `## Signals`.
|
|
30
|
+
> - `## Log format` lists no field that `docs/security.md` marks as personal data.
|
|
31
|
+
> - No example row remains.
|
|
32
|
+
|
|
33
|
+
# Observability
|
|
34
|
+
|
|
35
|
+
> [!CAUTION]
|
|
36
|
+
> **Purpose:** Logging architecture, correlation tracing, telemetry pipelines, error tracking and alerts.
|
|
37
|
+
>
|
|
38
|
+
> **Rules:**
|
|
39
|
+
>
|
|
40
|
+
> - Follow `.bkit/authoring.md` § Docs when you edit this file.
|
|
41
|
+
> - NEVER log PII. Scrub sensitive fields at the source.
|
|
42
|
+
> - Observability never blocks business logic.
|
|
43
|
+
>
|
|
44
|
+
> **Not here:** Smoke checks that probe a deployed release go in `docs/testing.md`. Downgraded signals go in `docs/noise.md`. Failure-evidence fetching for `/bkit-debug` is configured in `.agents/context.md`.
|
|
45
|
+
>
|
|
46
|
+
> **Update when:** A logger, signal, correlation identifier, error tracker, alert or log drain is added, changed or removed.
|
|
47
|
+
|
|
48
|
+
## Signal pipeline
|
|
49
|
+
|
|
50
|
+
[The path a signal takes from the application to the people who act on it.]
|
|
51
|
+
|
|
52
|
+
```mermaid
|
|
53
|
+
flowchart LR
|
|
54
|
+
APP["Application"] --> LOGS["Log drain"]
|
|
55
|
+
APP --> ERR["Error tracker"]
|
|
56
|
+
LOGS --> ALERT["Alert rules"]
|
|
57
|
+
ERR --> ALERT
|
|
58
|
+
ALERT --> PEOPLE["On-call people"]
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Log format
|
|
62
|
+
|
|
63
|
+
[The logger module, the call every log line goes through, and the fields each line carries.]
|
|
64
|
+
|
|
65
|
+
## Signals
|
|
66
|
+
|
|
67
|
+
<!-- prettier-ignore -->
|
|
68
|
+
| Signal | Kind | Emitted from | Lands in |
|
|
69
|
+
| --- | --- | --- | --- |
|
|
70
|
+
| [Signal name] | [Log event, span, metric or audit record.] | [Module that emits it.] | [Where it is stored or shown.] |
|
|
71
|
+
| [e.g., report.saved] | Log event | The report service. | The log drain. |
|
|
72
|
+
|
|
73
|
+
## Correlation
|
|
74
|
+
|
|
75
|
+
[The identifier that ties one request together across runtimes, and where it is set.]
|
|
76
|
+
|
|
77
|
+
## Error tracking
|
|
78
|
+
|
|
79
|
+
[The tool that collects errors and how an error reaches it.]
|
|
80
|
+
|
|
81
|
+
## Alerts
|
|
82
|
+
|
|
83
|
+
<!-- prettier-ignore -->
|
|
84
|
+
| Alert | Fires when | Threshold | Notifies |
|
|
85
|
+
| --- | --- | --- | --- |
|
|
86
|
+
| [Alert name] | [Signal or condition.] | [Limit and window.] | [Who is told.] |
|
|
87
|
+
| [e.g., Report failures] | The report service logs errors. | 5 in 10 minutes. | The on-call channel. |
|
|
88
|
+
|
|
89
|
+
## Where to look
|
|
90
|
+
|
|
91
|
+
<!-- prettier-ignore -->
|
|
92
|
+
| Question | Look in |
|
|
93
|
+
| --- | --- |
|
|
94
|
+
| [Question a person asks.] | [Tool and view.] |
|
|
95
|
+
| [e.g., Why did a report fail?] | The error tracker, then the log drain filtered by request identifier. |
|
|
96
|
+
|
|
97
|
+
## Open questions
|
|
98
|
+
|
|
99
|
+
[Each unresolved fact, who can answer it and which section it affects.]
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
> Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/security.md`, fill it in, then delete this introduction.
|
|
2
|
+
>
|
|
3
|
+
> **Fill these first:** `docs/architecture.md`.
|
|
4
|
+
>
|
|
5
|
+
> **Finish against:** `docs/data-schema.md` for the "Where stored" column of the `## PII` table.
|
|
6
|
+
>
|
|
7
|
+
> **Where the facts come from:** the authentication and session code, the route and permission definitions, the input-validation schemas, the secret stores and the CI secret configuration, and the data models that hold personal data.
|
|
8
|
+
>
|
|
9
|
+
> **Fill in:**
|
|
10
|
+
>
|
|
11
|
+
> 1. Copy this starter to `docs/security.md`.
|
|
12
|
+
> 2. Fill `## Trust boundaries` with where untrusted input enters the system. Read the runtimes from `docs/architecture.md`.
|
|
13
|
+
> 3. Fill `## Authentication` with how a user or service proves who it is. Redraw the sequence chart for one authenticated request.
|
|
14
|
+
> 4. Fill `## Authorization` with one row per role or service account and what it may do.
|
|
15
|
+
> 5. Fill `## Input validation` with where each kind of input is checked, on the server.
|
|
16
|
+
> 6. Fill `## Rate limiting` with each limited route or action and its limit.
|
|
17
|
+
> 7. Fill `## Secrets` with one row per secret: its name, the store that holds it, who can read it and how it rotates. Write names, never values.
|
|
18
|
+
> 8. Fill `## PII` with each kind of personal data and how it is protected. Leave "Where stored" to be finished once `docs/data-schema.md` exists.
|
|
19
|
+
> 9. Fill the `### This project` slot under `## Supply-Chain (GitHub Actions)` with the project's own dependency and CI rules. Keep the rest of that section.
|
|
20
|
+
> 10. Record unresolved facts under `## Open questions`.
|
|
21
|
+
> 11. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/security.md` | ● | ● | ● | ○ | ○ | Authentication, authorization, input validation, rate limiting, secrets management and PII handling. |
|
|
22
|
+
> 12. Check the document against each completion check, then delete this introduction.
|
|
23
|
+
>
|
|
24
|
+
> **If it does not apply:** write `Not applicable: {reason}` under a section that does not apply, such as `## Authentication` for a tool with no users.
|
|
25
|
+
>
|
|
26
|
+
> **Completion checks:**
|
|
27
|
+
>
|
|
28
|
+
> - The sequence chart matches the authentication code path.
|
|
29
|
+
> - Every secret the CI configuration or the code reads has a row in `## Secrets`.
|
|
30
|
+
> - Every service account has a row in `## Authorization`.
|
|
31
|
+
> - Every kind of personal data in `docs/data-schema.md` has a row in `## PII`.
|
|
32
|
+
> - No secret value appears in the document.
|
|
33
|
+
> - No example row remains.
|
|
34
|
+
|
|
35
|
+
# Security
|
|
36
|
+
|
|
37
|
+
> [!CAUTION]
|
|
38
|
+
> **Purpose:** Authentication, authorization, input validation, rate limiting, secrets management and PII handling.
|
|
39
|
+
>
|
|
40
|
+
> **Rules:**
|
|
41
|
+
>
|
|
42
|
+
> - Follow `.bkit/authoring.md` § Docs when you edit this file.
|
|
43
|
+
> - Auth standards live only here. Other docs link to this file and do not restate them.
|
|
44
|
+
> - Never write a secret value. Write its name and the store that holds it.
|
|
45
|
+
>
|
|
46
|
+
> **bkit practice:** `## Supply-Chain (GitHub Actions)` is bkit's own practice. Keep it and its heading, and put the project's own rules in its `### This project` slot. Sections marked **bkit practice** keep their heading text and stay separate sections. Do not rename, merge or compress them, because bkit's CI template, advisories and audits cite them by name.
|
|
47
|
+
>
|
|
48
|
+
> **Not here:** The variables a developer sets locally go in `docs/setup.md` § Environment variables. How each environment's config is synced goes in `docs/deployments.md` § Secrets and env config. The tables and fields that hold personal data go in `docs/data-schema.md`.
|
|
49
|
+
>
|
|
50
|
+
> **Update when:** A role, service account, secret, validation point, limit or kind of personal data is added, changed or removed.
|
|
51
|
+
|
|
52
|
+
## Trust boundaries
|
|
53
|
+
|
|
54
|
+
[Where untrusted input enters the system, and which runtime checks it.]
|
|
55
|
+
|
|
56
|
+
## Authentication
|
|
57
|
+
|
|
58
|
+
[How a user or service proves who it is, and how a session or token is kept.]
|
|
59
|
+
|
|
60
|
+
```mermaid
|
|
61
|
+
sequenceDiagram
|
|
62
|
+
participant U as User
|
|
63
|
+
participant A as Application
|
|
64
|
+
participant S as Session store
|
|
65
|
+
U->>A: Request with credentials
|
|
66
|
+
A->>S: Check the session
|
|
67
|
+
S-->>A: Identity
|
|
68
|
+
A-->>U: Response
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Authorization
|
|
72
|
+
|
|
73
|
+
<!-- prettier-ignore -->
|
|
74
|
+
| Role or service account | Kind | May | Granted by |
|
|
75
|
+
| --- | --- | --- | --- |
|
|
76
|
+
| [Role or service account] | [User role or service account.] | [What it may do.] | [Where the grant is defined.] |
|
|
77
|
+
| [e.g., Reviewer] | User role | Read and comment on reports. | The role table in the application. |
|
|
78
|
+
|
|
79
|
+
## Input validation
|
|
80
|
+
|
|
81
|
+
<!-- prettier-ignore -->
|
|
82
|
+
| Input | Checked in | How |
|
|
83
|
+
| --- | --- | --- |
|
|
84
|
+
| [Kind of input] | [Handler or layer.] | [Schema or rule.] |
|
|
85
|
+
| [e.g., Report form] | The report service handler. | A schema parsed on the server. |
|
|
86
|
+
|
|
87
|
+
## Rate limiting
|
|
88
|
+
|
|
89
|
+
<!-- prettier-ignore -->
|
|
90
|
+
| Route or action | Limit | Keyed by |
|
|
91
|
+
| --- | --- | --- |
|
|
92
|
+
| [Route or action] | [Requests per window.] | [User, address or token.] |
|
|
93
|
+
| [e.g., Sign-in] | 5 requests per minute. | Network address. |
|
|
94
|
+
|
|
95
|
+
## Secrets
|
|
96
|
+
|
|
97
|
+
<!-- prettier-ignore -->
|
|
98
|
+
| Secret name | Store | Who can read it | Rotation |
|
|
99
|
+
| --- | --- | --- | --- |
|
|
100
|
+
| [Secret name] | [Store that holds it.] | [Roles and service accounts.] | [How and how often it rotates.] |
|
|
101
|
+
| [e.g., SESSION_KEY] | The hosting platform's secret store. | The report service. | Every 90 days. |
|
|
102
|
+
|
|
103
|
+
## PII
|
|
104
|
+
|
|
105
|
+
<!-- prettier-ignore -->
|
|
106
|
+
| Personal data | Why it is held | Protection | Where stored |
|
|
107
|
+
| --- | --- | --- | --- |
|
|
108
|
+
| [Kind of personal data] | [Why the project holds it.] | [Encryption, masking or retention.] | [Table and field, from `docs/data-schema.md`.] |
|
|
109
|
+
| [e.g., Email address] | Account sign-in. | Never logged. | Users table, email field. |
|
|
110
|
+
|
|
111
|
+
## Supply-Chain (GitHub Actions)
|
|
112
|
+
|
|
113
|
+
> **bkit practice:** keep this section; bkit's audits and advisories cite its heading by name, so leave the heading text unchanged.
|
|
114
|
+
|
|
115
|
+
Action SHA-pinning and the dependency-update pipeline (Renovate / Dependabot, Trivy scan, CVE handling) are described in `deployments.md` § Dependency updaters. This section holds the security invariants only.
|
|
116
|
+
|
|
117
|
+
**Token isolation:**
|
|
118
|
+
|
|
119
|
+
- Renovate PRs get a restricted `GITHUB_TOKEN`.
|
|
120
|
+
- They have no access to the cloud lane's model-auth secrets (`secrets.BKIT_ANTHROPIC_API_KEY` / the provider `BKIT_` keys / `secrets.BKIT_OPENAI_API_KEY`).
|
|
121
|
+
- They have no access to federated Claude tokens either. Only a `bkit-cloud.yml` job that matches the federation rule mints those.
|
|
122
|
+
- `bkit-cloud.yml` does not dispatch on Renovate PRs.
|
|
123
|
+
- As a result, a compromised dependency PR cannot reach agent API credentials.
|
|
124
|
+
|
|
125
|
+
**Scanner isolation:** The CI vulnerability scanner (e.g. `bkit-trivy.yml`) runs with `contents: read`, `persist-credentials: false` and no secret. Its image or action is pinned by digest, never by a floating tag. Setup is in `.bkit/templates.md` § Trivy.
|
|
126
|
+
|
|
127
|
+
The untrusted-content rules bkit applies to every workflow are in `.bkit/prompts.md` § Untrusted Content & Prompt Injection.
|
|
128
|
+
|
|
129
|
+
### This project
|
|
130
|
+
|
|
131
|
+
> **Project slot:** the project's own dependency and CI rules, such as which updater it runs and who reviews its pull requests.
|
|
132
|
+
|
|
133
|
+
[The project's dependency and CI supply-chain rules.]
|
|
134
|
+
|
|
135
|
+
## Open questions
|
|
136
|
+
|
|
137
|
+
[Each unresolved fact, who can answer it and which section it affects.]
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
> Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/setup.md`, fill it in, then delete this introduction.
|
|
2
|
+
>
|
|
3
|
+
> **Fill these first:** `docs/technology.md`.
|
|
4
|
+
>
|
|
5
|
+
> **Finish against:** `docs/architecture.md` for `## Local services`, and `docs/security.md` for `## Environment variables`; both sections wait for the secrets and services those docs name.
|
|
6
|
+
>
|
|
7
|
+
> **Where the facts come from:** the package manifests and their scripts, the example environment file, the local service configuration, the CI configuration and a clean checkout run on a fresh machine.
|
|
8
|
+
>
|
|
9
|
+
> **Fill in:**
|
|
10
|
+
>
|
|
11
|
+
> 1. Copy this starter to `docs/setup.md`.
|
|
12
|
+
> 2. Fill `## Prerequisites` with the tools a developer installs first, and name the file that holds each required version.
|
|
13
|
+
> 3. Run the setup on a clean checkout, and write each command into `## First-time setup` in the order that worked.
|
|
14
|
+
> 4. Fill `## Environment variables` with what a developer sets on their own machine. Write names and where each value comes from, and never a secret value.
|
|
15
|
+
> 5. Fill `## Local services` with each local service, its start command and its reset command. An integration test run needs both.
|
|
16
|
+
> 6. Fill `## Everyday commands` with the commands a developer runs most, read from the manifest scripts.
|
|
17
|
+
> 7. Fill `## Troubleshooting` with the failures new contributors hit and the fix for each.
|
|
18
|
+
> 8. Record unresolved facts under `## Open questions`.
|
|
19
|
+
> 9. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/setup.md` | — | — | ○ | ○ | — | How a developer sets up and runs the project locally: prerequisites, first-time setup, environment variables, local services, everyday commands and troubleshooting. |
|
|
20
|
+
> 10. Check the document against each completion check, then delete this introduction.
|
|
21
|
+
>
|
|
22
|
+
> **If it does not apply:** write `Not applicable: {reason}` under a section that does not apply, such as `## Local services` for a project with none.
|
|
23
|
+
>
|
|
24
|
+
> **Completion checks:**
|
|
25
|
+
>
|
|
26
|
+
> - The first-time commands ran in order on a clean checkout.
|
|
27
|
+
> - Every local service has a start command and a reset command.
|
|
28
|
+
> - No secret value appears in the document.
|
|
29
|
+
> - No example row remains.
|
|
30
|
+
|
|
31
|
+
# Setup
|
|
32
|
+
|
|
33
|
+
> [!CAUTION]
|
|
34
|
+
> **Purpose:** How a developer sets up and runs the project locally: prerequisites, first-time setup, environment variables, local services, everyday commands and troubleshooting.
|
|
35
|
+
>
|
|
36
|
+
> **Rules:**
|
|
37
|
+
>
|
|
38
|
+
> - Follow `.bkit/authoring.md` § Docs when you edit this file.
|
|
39
|
+
> - Never write a secret value. Write its name and where it comes from.
|
|
40
|
+
> - Local seed data and test fixtures must NEVER run against a remote project.
|
|
41
|
+
>
|
|
42
|
+
> **Not here:** Secret names, stores and rotation go in `docs/security.md` § Secrets. How a deployed environment gets its configuration goes in `docs/deployments.md` § Secrets and env config. Agent host and remote access setup is in `.bkit/install.md`.
|
|
43
|
+
>
|
|
44
|
+
> **Update when:** A prerequisite, a setup command, an environment variable, a local service or a script changes.
|
|
45
|
+
|
|
46
|
+
## Prerequisites
|
|
47
|
+
|
|
48
|
+
<!-- prettier-ignore -->
|
|
49
|
+
| Tool | Needed for | Version from |
|
|
50
|
+
| --- | --- | --- |
|
|
51
|
+
| [Tool] | [What it is used for.] | [File that holds the version.] |
|
|
52
|
+
| [e.g., Language runtime] | Running and testing the project. | The version file in the repository root. |
|
|
53
|
+
|
|
54
|
+
## First-time setup
|
|
55
|
+
|
|
56
|
+
1. [The first command, and what it does.]
|
|
57
|
+
2. [The next command, and what it does.]
|
|
58
|
+
|
|
59
|
+
## Environment variables
|
|
60
|
+
|
|
61
|
+
<!-- prettier-ignore -->
|
|
62
|
+
| Variable | Used by | Where the value comes from |
|
|
63
|
+
| --- | --- | --- |
|
|
64
|
+
| [Variable name] | [What reads it.] | [Where a developer gets the value.] |
|
|
65
|
+
| [e.g., DATABASE_URL] | The local database client. | The example environment file. |
|
|
66
|
+
|
|
67
|
+
## Local services
|
|
68
|
+
|
|
69
|
+
<!-- prettier-ignore -->
|
|
70
|
+
| Service | Start command | Reset command |
|
|
71
|
+
| --- | --- | --- |
|
|
72
|
+
| [Service] | [Command that starts it.] | [Command that resets it to a clean state.] |
|
|
73
|
+
| [e.g., Local database] | The project's start script. | The project's reset script. |
|
|
74
|
+
|
|
75
|
+
## Everyday commands
|
|
76
|
+
|
|
77
|
+
<!-- prettier-ignore -->
|
|
78
|
+
| Task | Command |
|
|
79
|
+
| --- | --- |
|
|
80
|
+
| [Task] | [Command.] |
|
|
81
|
+
| [e.g., Run the unit tests] | The project's test script. |
|
|
82
|
+
|
|
83
|
+
## Troubleshooting
|
|
84
|
+
|
|
85
|
+
<!-- prettier-ignore -->
|
|
86
|
+
| Symptom | Cause | Fix |
|
|
87
|
+
| --- | --- | --- |
|
|
88
|
+
| [What the developer sees.] | [Why it happens.] | [What to do.] |
|
|
89
|
+
| [e.g., The database connection is refused] | The local database is not running. | Start the local services. |
|
|
90
|
+
|
|
91
|
+
## Open questions
|
|
92
|
+
|
|
93
|
+
[Each unresolved fact, who can answer it and which section it affects.]
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
> Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/technology.md`, fill it in, then delete this introduction.
|
|
2
|
+
>
|
|
3
|
+
> **Fill these first:** `docs/components.md`.
|
|
4
|
+
>
|
|
5
|
+
> **Finish against:** none.
|
|
6
|
+
>
|
|
7
|
+
> **Where the facts come from:** the package manifests and lockfiles, the build and tool configuration files, the CI configuration and the lint and format settings.
|
|
8
|
+
>
|
|
9
|
+
> **Fill in:**
|
|
10
|
+
>
|
|
11
|
+
> 1. Copy this starter to `docs/technology.md`.
|
|
12
|
+
> 2. List every layer the components in `docs/components.md` need, and read each layer's technology from the manifest or configuration file that declares it.
|
|
13
|
+
> 3. Fill `## Stack` with one row per technology. In `Version from`, name the file that holds the version, and never type the number.
|
|
14
|
+
> 4. Fill `## Conventions` with each rule a reviewer enforces, and name the tool or review step that enforces it.
|
|
15
|
+
> 5. Fill `## Not used` with technologies a contributor might expect, and name what the project uses instead.
|
|
16
|
+
> 6. Record unresolved facts under `## Open questions`.
|
|
17
|
+
> 7. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/technology.md` | ● | ● | ○ | ○ | ○ | Which frameworks, libraries and styling systems the project uses, and the coding conventions a reviewer enforces. Why a choice was made goes in `decisions.jsonl`. |
|
|
18
|
+
> 8. Check the document against each completion check, then delete this introduction.
|
|
19
|
+
>
|
|
20
|
+
> **If it does not apply:** every project uses some technology. Write `Not applicable: {reason}` under a section that does not apply, such as `## Not used` for a project with no alternatives in play.
|
|
21
|
+
>
|
|
22
|
+
> **Completion checks:**
|
|
23
|
+
>
|
|
24
|
+
> - Every layer in `docs/components.md` has a row in `## Stack`.
|
|
25
|
+
> - Every `Version from` cell names an existing file, and no version number is typed in the document.
|
|
26
|
+
> - Every convention names what enforces it.
|
|
27
|
+
> - No example row remains.
|
|
28
|
+
|
|
29
|
+
# Technology
|
|
30
|
+
|
|
31
|
+
> [!CAUTION]
|
|
32
|
+
> **Purpose:** Which frameworks, libraries and styling systems the project uses, and the coding conventions a reviewer enforces. Why a choice was made goes in `decisions.jsonl`.
|
|
33
|
+
>
|
|
34
|
+
> **Rules:**
|
|
35
|
+
>
|
|
36
|
+
> - Follow `.bkit/authoring.md` § Docs when you edit this file.
|
|
37
|
+
> - Name the file that holds a version, and never type a version number.
|
|
38
|
+
> - List each technology once, with how it is used.
|
|
39
|
+
>
|
|
40
|
+
> **Not here:** The reason for a choice goes in `decisions.jsonl`. Service boundaries and deployment topology go in `docs/architecture.md`. Setup commands go in `docs/setup.md`.
|
|
41
|
+
>
|
|
42
|
+
> **Update when:** A framework, library or styling system is added, replaced or removed, or a convention a reviewer enforces changes.
|
|
43
|
+
|
|
44
|
+
## Stack
|
|
45
|
+
|
|
46
|
+
<!-- prettier-ignore -->
|
|
47
|
+
| Layer | Technology | Version from | Chosen for |
|
|
48
|
+
| --- | --- | --- | --- |
|
|
49
|
+
| [Layer] | [Technology] | [File that holds the version.] | [What it is used for.] |
|
|
50
|
+
| [e.g., Web interface] | A component framework | The package manifest. | Rendering the report screens. |
|
|
51
|
+
|
|
52
|
+
## Conventions
|
|
53
|
+
|
|
54
|
+
<!-- prettier-ignore -->
|
|
55
|
+
| Convention | Rule | Enforced by |
|
|
56
|
+
| --- | --- | --- |
|
|
57
|
+
| [Convention] | [What a contributor does.] | [Tool or review step.] |
|
|
58
|
+
| [e.g., Formatting] | One formatter settings file for the whole repository. | The formatter check in CI. |
|
|
59
|
+
|
|
60
|
+
## Not used
|
|
61
|
+
|
|
62
|
+
<!-- prettier-ignore -->
|
|
63
|
+
| Technology | Use instead |
|
|
64
|
+
| --- | --- |
|
|
65
|
+
| [Technology a contributor might expect] | [What the project uses.] |
|
|
66
|
+
| [e.g., A second test runner] | The project's one test runner. |
|
|
67
|
+
|
|
68
|
+
## Open questions
|
|
69
|
+
|
|
70
|
+
[Each unresolved fact, who can answer it and which section it affects.]
|