@cbartens/bkit 6.1.0 → 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 +43 -33
- 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 +99 -36
- package/.bkit/core/.bkit/templates.md +167 -37
- 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 +161 -37
- package/.bkit/core/engine/checks/after/index.ts +18 -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 +124 -19
- package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
- package/.bkit/core/engine/commands/install/doctor.ts +5 -5
- 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 +202 -26
- 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 +46 -11
- 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/context/bkit-vercel.md +103 -59
- 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-check-accepted-divergences.mjs +1 -6
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
- package/.bkit/templates/slop-scan.config.json +2 -0
- package/CHANGELOG.md +79 -0
- package/DETAILS.md +661 -0
- package/README.md +73 -604
- package/dist/checks/after/auth.js +114 -46
- package/dist/checks/after/github.js +138 -35
- package/dist/checks/after/index.js +16 -4
- 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 +113 -20
- package/dist/commands/ci/push-gate.js +79 -44
- package/dist/commands/install/doctor.js +5 -5
- 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 +190 -27
- 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 +21 -12
- 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 +23 -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,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.]
|