@cbartens/bkit 5.5.1 → 6.1.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 +167 -154
- package/.bkit/core/.agents/context.md +95 -29
- package/.bkit/core/.agents/docs.md +18 -15
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
- package/.bkit/core/.agents/rules.md +112 -102
- package/.bkit/core/.agents/skills.md +63 -15
- package/.bkit/core/.bkit/README.md +167 -154
- package/.bkit/core/.bkit/authoring.md +747 -0
- package/.bkit/core/.bkit/cli.md +407 -0
- package/.bkit/core/.bkit/cloud.md +283 -195
- package/.bkit/core/.bkit/comparison.md +45 -43
- package/.bkit/core/.bkit/install.md +166 -95
- package/.bkit/core/.bkit/jsonl.md +339 -196
- package/.bkit/core/.bkit/pipeline.md +142 -145
- package/.bkit/core/.bkit/prompts.md +295 -264
- package/.bkit/core/.bkit/providers.md +460 -277
- package/.bkit/core/.bkit/router.md +69 -0
- package/.bkit/core/.bkit/templates.md +530 -256
- package/.bkit/core/.bkit/trackers.md +116 -65
- package/.bkit/core/.bkit/workflows.md +742 -618
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
- package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
- package/.bkit/core/AGENTS.md +6 -80
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
- package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
- package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
- package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
- package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
- package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
- package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
- package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
- package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
- package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
- package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
- package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
- package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
- package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
- package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
- package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
- package/.bkit/core/docs/templates/bkit-plan.md +158 -281
- package/.bkit/core/engine/checks/after/auth.ts +40 -37
- package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
- package/.bkit/core/engine/checks/after/github.ts +95 -17
- package/.bkit/core/engine/checks/after/index.ts +21 -8
- package/.bkit/core/engine/checks/after/suppression.ts +8 -5
- package/.bkit/core/engine/checks/after/tools.ts +125 -123
- package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
- package/.bkit/core/engine/checks/before/env.ts +3 -3
- package/.bkit/core/engine/checks/before/files.ts +5 -4
- package/.bkit/core/engine/checks/before/index.ts +25 -1
- package/.bkit/core/engine/checks/before/repo.ts +208 -2
- package/.bkit/core/engine/checks/status-holes.ts +916 -123
- package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
- package/.bkit/core/engine/checks/tips/detect.ts +66 -0
- package/.bkit/core/engine/checks/tips/index.ts +52 -11
- package/.bkit/core/engine/cli.ts +251 -130
- package/.bkit/core/engine/commands/analysis.ts +282 -199
- package/.bkit/core/engine/commands/ci/ci.ts +363 -29
- package/.bkit/core/engine/commands/ci/pins.ts +172 -0
- package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
- package/.bkit/core/engine/commands/comply.ts +77 -103
- package/.bkit/core/engine/commands/install/doctor.ts +2 -2
- package/.bkit/core/engine/commands/install/install.ts +57 -18
- package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
- package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
- package/.bkit/core/engine/commands/land.ts +139 -18
- package/.bkit/core/engine/commands/lib.ts +381 -22
- package/.bkit/core/engine/commands/registry.ts +10 -2
- package/.bkit/core/engine/commands/setup/setup.ts +8 -7
- package/.bkit/core/engine/commands/stats.ts +260 -0
- package/.bkit/core/engine/commands/tips.ts +10 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
- package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
- package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
- package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
- package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
- package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
- package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
- package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
- package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
- package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
- package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
- package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
- package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
- package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
- package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
- package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
- package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
- package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
- package/.bkit/core/engine/commands/workflow/status.ts +329 -33
- package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
- package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
- package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
- package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
- package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
- package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
- package/.bkit/core/engine/install/cloud-env.ts +251 -121
- package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
- package/.bkit/core/engine/install/manifest.ts +67 -17
- package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
- package/.bkit/core/engine/install/modules/cloud.ts +24 -16
- package/.bkit/core/engine/install/modules/codex.ts +15 -2
- package/.bkit/core/engine/install/modules/core.ts +1196 -45
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/opencode.ts +18 -6
- package/.bkit/core/engine/install/template-notes.ts +130 -0
- package/.bkit/core/engine/install/version-file.ts +9 -4
- package/.bkit/core/engine/install/write.ts +5 -0
- package/.bkit/core/engine/ledgers/compact.ts +124 -0
- package/.bkit/core/engine/ledgers/journal.ts +291 -0
- package/.bkit/core/engine/ledgers/migrate.ts +92 -0
- package/.bkit/core/engine/ledgers/status.ts +249 -21
- package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
- package/.bkit/core/engine/render/hosts.ts +118 -14
- package/.bkit/core/engine/render/models.ts +12 -0
- package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
- package/.bkit/core/engine/shared/branches.ts +4 -1
- package/.bkit/core/engine/shared/dep-updater.ts +60 -0
- package/.bkit/core/engine/shared/egress.ts +8 -1
- package/.bkit/core/engine/shared/json.ts +25 -7
- package/.bkit/core/engine/shared/package-manager.ts +9 -0
- package/.bkit/core/engine/shared/settings.ts +243 -31
- package/.bkit/core/engine/shared/text.ts +361 -0
- package/.bkit/core/engine/shared/timeouts.ts +2 -0
- package/.bkit/core/engine/tools/cli-doc.ts +111 -0
- package/.bkit/core/engine/tools/grammar-density.ts +215 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
- package/.bkit/core/engine/tools/instructions.ts +1802 -0
- package/.bkit/core/hooks/antigravity-hook.js +25 -10
- package/.bkit/core/hooks/gateguard-engine.js +54 -29
- package/.bkit/core/hooks/guardrails-shell.js +4 -5
- package/.bkit/core/hooks/guardrails-tiers.js +10 -4
- package/.bkit/core/hooks/preflight-linear.sh +9 -9
- package/.bkit/core/hooks/preflight-rules.sh +8 -0
- package/.bkit/core/hooks/readguard-engine.js +29 -10
- package/.bkit/core/hooks/session-rules-advisory.js +61 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
- package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
- package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
- package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
- package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
- package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
- package/.bkit/core/prompts/bkit-design-generate.md +80 -46
- package/.bkit/core/prompts/bkit-design-organise.md +83 -32
- package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
- package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
- package/.bkit/core/prompts/bkit-design-spike.md +64 -40
- package/.bkit/core/prompts/bkit-design-update.md +53 -28
- package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
- package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
- package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
- package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
- package/.bkit/core/prompts/bkit-plan-update.md +86 -31
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
- package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
- package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
- package/.bkit/core/workflows/bkit-auto.md +89 -58
- package/.bkit/core/workflows/bkit-build.md +967 -517
- package/.bkit/core/workflows/bkit-debug.md +555 -387
- package/.bkit/core/workflows/bkit-design.md +319 -283
- package/.bkit/core/workflows/bkit-plan.md +319 -342
- package/.bkit/core/workflows/bkit-ship.md +525 -328
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
- package/.bkit/shared/.bkit/.env.example +2 -2
- package/.bkit/shared/.claude/bkit-cloud.md +12 -10
- package/.bkit/shared/.claude/settings.json +14 -0
- package/.bkit/shared/.codex/bkit-cloud.md +98 -0
- package/.bkit/shared/.codex/hooks.json +20 -0
- package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
- package/.bkit/shared/.cursor/mcp.json +1 -1
- package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
- package/.bkit/shared/.gitattributes +1 -1
- package/.bkit/shared/.mcp.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +12 -1
- package/.bkit/shared/CLAUDE.md +6 -2
- package/.bkit/shared/GEMINI.md +5 -2
- package/.bkit/shared/docs/architecture.md +4 -7
- package/.bkit/shared/docs/data-schema.md +4 -7
- package/.bkit/shared/docs/deployments.md +241 -168
- package/.bkit/shared/docs/design.md +11 -12
- package/.bkit/shared/docs/noise.md +8 -7
- package/.bkit/shared/docs/observability.md +5 -8
- package/.bkit/shared/docs/security.md +35 -17
- package/.bkit/shared/docs/setup.md +29 -18
- package/.bkit/shared/docs/technology.md +3 -6
- package/.bkit/shared/docs/testing.md +289 -174
- package/.bkit/shared/gitignore +6 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
- package/.bkit/templates/.cursor/Dockerfile +12 -8
- package/.bkit/templates/.cursor/environment.json +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
- package/.bkit/templates/.github/renovate.json5 +34 -6
- package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
- package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
- package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
- package/.bkit/templates/.husky/pre-commit +2 -2
- package/.bkit/templates/.husky/pre-push +96 -36
- package/.bkit/templates/.prettierignore +6 -0
- package/.bkit/templates/.vale.ini +27 -27
- package/.bkit/templates/context/bkit-cloudrun.md +23 -15
- package/.bkit/templates/context/bkit-expo.md +70 -52
- package/.bkit/templates/context/bkit-github.md +93 -56
- package/.bkit/templates/context/bkit-inngest.md +21 -15
- package/.bkit/templates/context/bkit-maestro.md +22 -16
- package/.bkit/templates/context/bkit-playwright.md +23 -17
- package/.bkit/templates/context/bkit-resend.md +12 -10
- package/.bkit/templates/context/bkit-sentry.md +30 -20
- package/.bkit/templates/context/bkit-serena.md +8 -7
- package/.bkit/templates/context/bkit-stripe.md +14 -13
- package/.bkit/templates/context/bkit-supabase.md +16 -13
- package/.bkit/templates/context/bkit-tavily.md +14 -11
- package/.bkit/templates/context/bkit-vercel.md +27 -18
- package/.bkit/templates/docs/capabilities.md +15 -14
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
- package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
- package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
- package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
- package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
- package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
- package/.bkit/templates/slop-scan.config.json +9 -2
- package/CHANGELOG.md +231 -0
- package/README.md +278 -89
- package/dist/checks/after/auth.js +36 -33
- package/dist/checks/after/ci-yml.js +91 -30
- package/dist/checks/after/github.js +91 -17
- package/dist/checks/after/index.js +22 -11
- package/dist/checks/after/suppression.js +8 -5
- package/dist/checks/after/tools.js +111 -114
- package/dist/checks/before/context-fetch.js +218 -33
- package/dist/checks/before/env.js +3 -3
- package/dist/checks/before/files.js +5 -3
- package/dist/checks/before/index.js +20 -3
- package/dist/checks/before/repo.js +197 -2
- package/dist/checks/status-holes.js +739 -114
- package/dist/checks/tips/catalogue.js +70 -19
- package/dist/checks/tips/detect.js +62 -0
- package/dist/checks/tips/index.js +51 -9
- package/dist/cli.js +234 -124
- package/dist/commands/analysis.js +174 -141
- package/dist/commands/ci/ci.js +302 -25
- package/dist/commands/ci/pins.js +142 -0
- package/dist/commands/ci/push-gate.js +194 -0
- package/dist/commands/comply.js +54 -91
- package/dist/commands/install/doctor.js +2 -2
- package/dist/commands/install/install.js +50 -19
- package/dist/commands/install/uninstall.js +82 -55
- package/dist/commands/install/upgrade.js +21 -11
- package/dist/commands/land.js +137 -17
- package/dist/commands/lib.js +295 -21
- package/dist/commands/registry.js +10 -2
- package/dist/commands/setup/setup.js +8 -7
- package/dist/commands/stats.js +175 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +1873 -152
- package/dist/commands/workflow/challenge.js +609 -0
- package/dist/commands/workflow/completeness.js +97 -0
- package/dist/commands/workflow/context.js +1045 -46
- package/dist/commands/workflow/counters.js +385 -86
- package/dist/commands/workflow/decisions.js +484 -0
- package/dist/commands/workflow/disk.js +214 -56
- package/dist/commands/workflow/fids.js +706 -33
- package/dist/commands/workflow/issues.js +349 -59
- package/dist/commands/workflow/ledgers.js +1123 -37
- package/dist/commands/workflow/locks.js +26 -2
- package/dist/commands/workflow/plan-blocks.js +501 -0
- package/dist/commands/workflow/plan-versions.js +22 -0
- package/dist/commands/workflow/plans.js +205 -0
- package/dist/commands/workflow/prs.js +154 -35
- package/dist/commands/workflow/repo.js +58 -8
- package/dist/commands/workflow/roadmap.js +58 -23
- package/dist/commands/workflow/run-facts.js +421 -0
- package/dist/commands/workflow/runs.js +670 -72
- package/dist/commands/workflow/runtime.js +15 -1
- package/dist/commands/workflow/skills.js +1 -0
- package/dist/commands/workflow/status.js +282 -34
- package/dist/commands/workflow/step-table.js +308 -0
- package/dist/commands/workflow/steps.js +703 -96
- package/dist/commands/workflow/summary-findings.js +117 -0
- package/dist/commands/workflow/summary.js +388 -0
- package/dist/commands/workflow/tasks.js +378 -0
- package/dist/commands/workflow/test-blocks.js +231 -0
- package/dist/commands/workflow/tests-changed.js +172 -0
- package/dist/commands/workflow/tests.js +1695 -305
- package/dist/commands/workflow/tracker.js +983 -0
- package/dist/commands/workflow/workflows.js +1014 -222
- package/dist/commands/workflow/worktrees.js +432 -26
- package/dist/install/cloud-env.js +233 -99
- package/dist/install/context-ci-workflow.js +85 -0
- package/dist/install/manifest.js +64 -17
- package/dist/install/modules/antigravity.js +3 -2
- package/dist/install/modules/cloud.js +25 -16
- package/dist/install/modules/codex.js +12 -2
- package/dist/install/modules/core.js +1090 -48
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/opencode.js +13 -7
- package/dist/install/template-notes.js +116 -0
- package/dist/install/version-file.js +9 -4
- package/dist/ledgers/compact.js +87 -0
- package/dist/ledgers/journal.js +233 -0
- package/dist/ledgers/migrate.js +81 -0
- package/dist/ledgers/status.js +176 -13
- package/dist/ledgers/telemetry.js +1010 -125
- package/dist/render/hosts.js +104 -14
- package/dist/render/models.js +12 -0
- package/dist/shared/bkit-latest.js +26 -4
- package/dist/shared/branches.js +3 -1
- package/dist/shared/dep-updater.js +49 -0
- package/dist/shared/egress.js +8 -1
- package/dist/shared/json.js +20 -7
- package/dist/shared/package-manager.js +6 -0
- package/dist/shared/settings.js +181 -24
- package/dist/shared/text.js +333 -0
- package/dist/shared/timeouts.js +2 -0
- package/dist/tools/cli-doc.js +97 -0
- package/dist/tools/grammar-density.js +183 -0
- package/dist/tools/instructions-sources.js +720 -0
- package/dist/tools/instructions.js +1623 -0
- package/package.json +156 -51
- package/.bkit/core/.bkit/lite.md +0 -73
- package/.bkit/core/engine/commands/harvest.ts +0 -459
- package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
- package/.bkit/core/engine/tools/wording.ts +0 -748
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
- package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
- package/.bkit/core/prompts/bkit-build-summary.md +0 -94
- package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
- package/.bkit/core/prompts/bkit-design-summary.md +0 -107
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
- package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
- package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
- package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
- package/dist/commands/harvest.js +0 -353
- package/dist/commands/workflow/workstreams.js +0 -143
- package/dist/tools/wording.js +0 -680
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
- /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
- /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
|
@@ -1,82 +1,51 @@
|
|
|
1
|
-
<!-- Note: Plans live at `docs/plans/{YYYYMM}/{FID}-plan.md` (canonical month bucket). `{YYYYMM}` = creation month, set once by the first workflow run for `{FID}`. Logs sit at `docs/plans/{YYYYMM}/logs/{FID}/` and are delete-eligible. The canonical copy is stamped with a `bkit:anchor` block recording the base commit (`baseSha`), its ref (`baseRef`), and the design it targets (`designPath`, `designBaseSha`); never hand-author or edit it. `@bkit-plan-generate` fills this template. -->
|
|
2
|
-
|
|
3
1
|
<!-- bkit:start -->
|
|
4
2
|
|
|
5
3
|
{{BKIT_MANAGED_MARKER}}
|
|
6
4
|
|
|
5
|
+
<!-- Note: @bkit-plan-generate fills this template. The plan lives at `docs/plans/{YYYYMM}/{FID}-plan.md`, the canonical month bucket, where `{YYYYMM}` is the month the first workflow run for `{FID}` created it, set once. Logs sit at `docs/plans/{YYYYMM}/logs/{FID}/`, and may be deleted. The canonical copy is stamped with a `bkit:anchor` block that records the base commit (`baseSha`), its ref (`baseRef`) and the design it targets (`designPath`, `designBaseSha`). NEVER write or edit that block by hand. -->
|
|
6
|
+
|
|
7
7
|
# [Plan Title] Implementation Plan
|
|
8
8
|
|
|
9
9
|
> [!CAUTION]
|
|
10
|
-
> **Purpose:**
|
|
11
|
-
>
|
|
12
|
-
> **Rules:**
|
|
13
|
-
>
|
|
14
|
-
> - Any tools mentioned below are examples only; swap for actual tools in final output; drop inapplicable.
|
|
15
|
-
> - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
|
|
16
|
-
> - Read `.agents/docs.md` → load docs for workflow / step / task; skip missing; cite docs inline where required.
|
|
17
|
-
> - Read this document once at session start; do not trust session memory; do not re-read on every loop iteration.
|
|
18
|
-
> - Source of truth: literal `[x]` vs `[ ]` checkboxes in this document; `[ ]` means not DONE regardless of context.
|
|
10
|
+
> **Purpose:** The implementation plan: pre-flight checks, gates, the runbook, verification and rollback.
|
|
19
11
|
|
|
20
12
|
## Context & Goals
|
|
21
13
|
|
|
22
|
-
[
|
|
23
|
-
|
|
24
|
-
> Success criteria once in `Acceptance Scenario → Success Criteria`; each runbook task has own `Done when`. Do not restate success list here.
|
|
14
|
+
[The problem or feature, and why it is needed. Initially set to `PENDING`.]
|
|
25
15
|
|
|
26
16
|
**Related Issues:**
|
|
27
17
|
|
|
28
|
-
- [
|
|
18
|
+
- [One `#N — title (state)` line per related issue. **If** none → `None`. Initially set to `PENDING`.]
|
|
29
19
|
|
|
30
20
|
---
|
|
31
21
|
|
|
32
22
|
## 👤 ⚠️ Acceptance Scenario
|
|
33
23
|
|
|
34
24
|
> [!CAUTION]
|
|
35
|
-
>
|
|
36
|
-
>
|
|
25
|
+
> 🛑 The owner reads and confirms this section.
|
|
26
|
+
> This is the feature's testable contract. The implementation, the tests and the verification all follow from what you confirm here, so a mistake here carries into every later step.
|
|
37
27
|
>
|
|
38
|
-
> **You only need 👤-marked sections** (Acceptance Scenario, Breaking Changes, Open Questions & Assumptions).
|
|
39
|
-
|
|
40
|
-
### Spec
|
|
41
|
-
|
|
42
|
-
> [!IMPORTANT]
|
|
43
|
-
> What good looks like; canonical for the plan phase. Subagents (plan generate, plan review, plan summary) must follow this spec. No plan subagent restates rules; this section = single source of truth for the plan.
|
|
44
|
-
|
|
45
|
-
- **Narrative:** 1–2 sentences, user POV (not system POV). User action + what they get back. Source, first that carries it wins: design `## Acceptance Scenario` → verbatim; issue `Narrative` (change shape, `.bkit/trackers.md` § Issue shapes) → verbatim; audits only (`docs/audits/`) → user/operator impact from in-scope findings. None → both fields = `⚠️ MISSING: no design doc, no issue Narrative and no audit report — human must provide before plan proceeds`; never fabricate; Gate 1 blocked until human fills.
|
|
46
|
-
- **Success Criteria:** <=5 bullets, measurable / testable. Outcomes (e.g. "user sees their event in the list within 2s"), not steps (e.g. "call API, render component"). Design count ≠ 5 → smallest set proving feature. Design → verbatim. No design → issue `Success Criteria` verbatim. Audits only → one bullet per in-scope finding id from `Expected`; no 5-bullet cap.
|
|
47
|
-
- **Process Sketch:** Design → plan inherits/refines. same happy-path (`Concrete Example`) + branches (`Edge Cases`) as `WHEN X → THEN Y` (3–7 lines); reuse exact examples, do not invent. Outcomes, not steps.
|
|
48
|
-
- **Key Edge Cases:** Design → plan inherits. Concurrency, conflicts, failures, cross-feature — not trivial validation (plan adds that).
|
|
49
|
-
- **Edge Cases:** Plan phase — design Key Edge Cases verbatim (no design → issue `Edge Cases` rows verbatim) + validation / error / boundary cases.
|
|
50
|
-
- **Concrete Example:** Plan phase only. Role, starting state, numbered steps, observable outcome. One scenario, not a list.
|
|
51
|
-
- **Derived Test Matrix:** Plan phase only. One row per testable behaviour → exactly one `Agent Execution Runbook` task. No row without a target file. In-scope audit behaviour → one row. Issue `Derived Test Matrix` rows → kept verbatim; add missing rows.
|
|
28
|
+
> **You only need 👤-marked sections** (Acceptance Scenario, Breaking Changes, Open Questions & Assumptions). The agent handles the rest.
|
|
52
29
|
|
|
53
30
|
### Narrative
|
|
54
31
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
[Copied verbatim from `{FID}-design.md` § Acceptance Scenario → Narrative. No design → per Spec above; initially set to `PENDING`.]
|
|
32
|
+
[One or two sentences from the user's side: what they do, and what they get back. Initially set to `PENDING`.]
|
|
58
33
|
|
|
59
34
|
### Success Criteria
|
|
60
35
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
[Copied verbatim from `{FID}-design.md` § Acceptance Scenario → Success Criteria. No design → per Spec above; initially set to `PENDING`.]
|
|
36
|
+
[Up to 5 measurable outcomes. Initially set to `PENDING`.]
|
|
64
37
|
|
|
65
38
|
### Process Sketch
|
|
66
39
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
- **
|
|
70
|
-
- **WHEN** [next step] **→ THEN** [outcome]
|
|
71
|
-
- **IF** [edge case / failure — mirrors an Edge Cases row] **→ THEN** [handling]
|
|
40
|
+
- **WHEN** [the trigger or user action] **→ THEN** [the observable outcome]
|
|
41
|
+
- **WHEN** [the next step] **→ THEN** [its outcome]
|
|
42
|
+
- **IF** [an edge case or failure, mirroring an Edge Cases row] **→ THEN** [how it is handled]
|
|
72
43
|
|
|
73
|
-
|
|
44
|
+
_e.g.,_ **WHEN** a user submits the form with a valid file **→ THEN** it is queued and a receipt is shown; **IF** the file is malformed **→ THEN** it is rejected inline and nothing is queued.
|
|
74
45
|
|
|
75
46
|
### Concrete Example
|
|
76
47
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
**Setup:** [User role, existing state, context]
|
|
48
|
+
**Setup:** [The user's role, the existing state and the context]
|
|
80
49
|
|
|
81
50
|
**Steps:**
|
|
82
51
|
|
|
@@ -84,398 +53,306 @@ _notation, e.g._ **WHEN** a user submits the form with a valid file **→ THEN**
|
|
|
84
53
|
2. User [does X] → System [responds with Y]
|
|
85
54
|
3. …
|
|
86
55
|
|
|
87
|
-
**Outcome:** [
|
|
56
|
+
**Outcome:** [The end state the user sees that proves success]
|
|
88
57
|
|
|
89
58
|
### Edge Cases
|
|
90
59
|
|
|
91
|
-
> Plan expands from design's Key Edge Cases.
|
|
92
|
-
|
|
93
60
|
<!-- prettier-ignore -->
|
|
94
61
|
| Scenario | Expected Behavior |
|
|
95
62
|
| --- | --- |
|
|
96
|
-
| [
|
|
97
|
-
| [e.g., concurrent edit from another device] | [e.g., last
|
|
63
|
+
| [a design Key Edge Case, or a case the plan adds] | [the specific behavior] |
|
|
64
|
+
| [e.g., a concurrent edit from another device] | [e.g., the last write wins, with no crash] |
|
|
98
65
|
|
|
99
66
|
### Derived Test Matrix
|
|
100
67
|
|
|
101
|
-
|
|
102
|
-
>
|
|
103
|
-
> **Discrimination (no false-green):** assertion MUST hit the **affected** surface and FAIL if behaviour broken — not transport status (200/201), not proxy surfaces, never mock away the boundary under test.
|
|
104
|
-
|
|
105
|
-
**Tier Key** — use these exact tier names in the `Type` column (they must match `docs/testing.md`); pick the **lowest tier that actually exercises** the behaviour (a behaviour may need several):
|
|
106
|
-
|
|
107
|
-
<!-- prettier-ignore -->
|
|
108
|
-
| Tier | Use for | Example behaviour |
|
|
109
|
-
| --- | --- | --- |
|
|
110
|
-
| **Static** | every change — type / lint / format / prose / drift (global gate, not a per-feature row) | `tsc`, lint, and `bkit check` pass on the changed files |
|
|
111
|
-
| **Unit** | pure function / single module, no I/O | service parses a payload correctly |
|
|
112
|
-
| **Integration** | crosses a LOCAL stateful boundary (own DB / API), no mocks at the boundary, fresh instance | API endpoint enforces tenant isolation against a fresh local instance |
|
|
113
|
-
| **@live (golden)** | crosses an EXTERNAL / DEPLOYED boundary (3rd-party API, model, payment, deployed schema, RLS) — reach it, assert a ground-truth signal | a real 3rd-party API returns content and a boundary-only identity |
|
|
114
|
-
| **E2E** | user-visible UI flow / DOM state | user creates an event and sees it in the list |
|
|
115
|
-
| **fresh-DB replay** | new / changed migration or seed (`bkit-tests-migration`) | migration replays from empty and the seed loads |
|
|
116
|
-
| **Smoke** | post-deploy health of a deployed surface (global observability gate) | deployed health route returns 200 |
|
|
117
|
-
|
|
118
|
-
One row per behaviour (copy the tier name from the key above verbatim into `Type`):
|
|
68
|
+
`Type` is a tier from `docs/testing.md`: Static, Unit, Integration, @live (golden), E2E, fresh-DB replay or Smoke. `Task` is the one runbook task that lands the row's test.
|
|
119
69
|
|
|
120
70
|
<!-- prettier-ignore -->
|
|
121
|
-
| Test description | Type | Target file |
|
|
122
|
-
| --- | --- | --- |
|
|
123
|
-
| [e.g.,
|
|
124
|
-
| [e.g.,
|
|
125
|
-
| [e.g., API endpoint enforces tenant isolation] | Integration | [e.g
|
|
126
|
-
| [e.g.,
|
|
127
|
-
| [e.g.,
|
|
71
|
+
| Test description | Type | Target file | Task |
|
|
72
|
+
| --- | --- | --- | --- |
|
|
73
|
+
| [e.g., happy path: a user creates an event and sees it in the list] | E2E | [e.g., `apps/web/e2e/[feature].spec.ts`] | 2 |
|
|
74
|
+
| [e.g., the service parses the payload correctly] | Unit | [e.g., `packages/[pkg]/[module].test.ts`] | 2 |
|
|
75
|
+
| [e.g., the API endpoint enforces tenant isolation] | Integration | [e.g., `packages/api/[feature].integration.test.ts`] | 2 |
|
|
76
|
+
| [e.g., the real third-party API returns the expected shape and a boundary-only identity, not just "did not throw"] | @live (golden) | [e.g., `packages/[pkg]/[feature].live.test.ts`] | 2 |
|
|
77
|
+
| [e.g., the new migration replays from empty and the seed loads] | fresh-DB replay | [e.g., `packages/db/migrations/*`] (replayed by `bkit-tests-migration`) | 1 |
|
|
128
78
|
|
|
129
79
|
### 👤 ✅ Human Confirmation
|
|
130
80
|
|
|
131
81
|
- [ ] **Acceptance Scenario confirmed:** I have reviewed the Narrative, Success Criteria, Process Sketch, Concrete Example, Edge Cases, and Derived Test Matrix above. They correctly describe what "done" looks like.
|
|
132
82
|
|
|
133
|
-
> [!CAUTION]
|
|
134
|
-
> **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
|
|
135
|
-
|
|
136
83
|
---
|
|
137
84
|
|
|
138
85
|
## 👤 ⚠️ Breaking Changes & Naming Review
|
|
139
86
|
|
|
140
87
|
> [!CAUTION]
|
|
141
|
-
>
|
|
142
|
-
> Review proposed names and breaking changes below.
|
|
88
|
+
> 🛑 The owner reads and confirms this section.
|
|
143
89
|
|
|
144
|
-
[
|
|
90
|
+
[Each proposed name (page, file, database table, route, API contract) and each breaking change (database structure, global layout). **If** none → `None`. Initially set to `PENDING`.]
|
|
145
91
|
|
|
146
92
|
### 👤 ✅ Human Confirmation
|
|
147
93
|
|
|
148
|
-
- [ ] **Breaking Changes confirmed:** I have reviewed
|
|
149
|
-
|
|
150
|
-
> [!CAUTION]
|
|
151
|
-
> **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
|
|
94
|
+
- [ ] **Breaking Changes confirmed:** I have reviewed every breaking change and naming decision above.
|
|
152
95
|
|
|
153
96
|
---
|
|
154
97
|
|
|
155
98
|
## 👤 ⚠️ Open Questions & Assumptions
|
|
156
99
|
|
|
157
100
|
> [!CAUTION]
|
|
158
|
-
>
|
|
159
|
-
>
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
- **
|
|
164
|
-
- **
|
|
165
|
-
- **Options:** A — [option, trade-off] · B — [option, trade-off] · C — [option, trade-off, optional]
|
|
166
|
-
- **Recommended:** [A] — [why, 1 line]
|
|
101
|
+
> 🛑 The owner reads and confirms this section.
|
|
102
|
+
> These are the unknowns and assumptions this plan relies on. An unresolved question is a risk, and a wrong assumption breaks what follows. **If** there are none → write `None`.
|
|
103
|
+
|
|
104
|
+
- **Assumption:** [what the plan takes as given] → [what breaks if it is wrong]
|
|
105
|
+
- **Open Question:** [the decision needed] → [who resolves it, and how]
|
|
106
|
+
- **Options:** A) [option] — [trade-off] · B) [option] — [trade-off] · C) [option] — [trade-off, optional]
|
|
107
|
+
- **Recommended:** A) [option] — [why, in one line]
|
|
167
108
|
- **Default if unanswered:** [what the agent proceeds with]
|
|
168
109
|
|
|
169
110
|
### 👤 ✅ Human Confirmation
|
|
170
111
|
|
|
171
112
|
- [ ] **Open Questions & Assumptions confirmed:** I have resolved or explicitly accepted every open question and assumption above.
|
|
172
113
|
|
|
173
|
-
> [!CAUTION]
|
|
174
|
-
> **Agent:** Do not pass Gate 1 until this checkbox is `[x]`.
|
|
175
|
-
|
|
176
114
|
---
|
|
177
115
|
|
|
178
116
|
## Alternative Approaches & Recommendations
|
|
179
117
|
|
|
180
|
-
[
|
|
181
|
-
|
|
182
|
-
**Selection Rule:** pick the approach with the best quality-of-end-state, not the smallest diff / lowest cost-of-change. In-scope work = complete or explicitly moved to `Out of Scope` — no 90% solutions or silent shortcuts.
|
|
118
|
+
[The paths rejected and why, and recommendations for a future phase. Initially set to `PENDING`.]
|
|
183
119
|
|
|
184
120
|
## Out of Scope
|
|
185
121
|
|
|
186
|
-
[
|
|
122
|
+
[Each excluded item, marked `Exempt`. **If** none → `None`. Initially set to `PENDING`.]
|
|
187
123
|
|
|
188
124
|
<!-- prettier-ignore -->
|
|
189
125
|
| Excluded item | Why `Exempt` | Where it belongs |
|
|
190
126
|
| --- | --- | --- |
|
|
191
|
-
| [feature
|
|
192
|
-
|
|
193
|
-
> [!CAUTION]
|
|
194
|
-
> **Default = in-scope.** `Exempt` only if genuinely-additive — not required by `Success Criteria`, `Acceptance Scenario` / `Derived Test Matrix` row, or design (non-goals excepted). Required items → runbook task, never deferral; parking here = `Blocking` deferral → plan review / scope-check pulls back. Mirror each `Exempt` row in `docs/deferrals.jsonl`. Audit `LOW` → `Exempt` rows here.
|
|
127
|
+
| [the excluded feature or fix] | [why it only adds to the plan's goal] | [a design non-goal, a follow-up issue or a future phase] |
|
|
128
|
+
| [e.g., bulk status change] | [e.g., single changes meet the goal, and bulk changes add to it] | [e.g., follow-up #N] |
|
|
195
129
|
|
|
196
130
|
## Suggested Scope Expansion
|
|
197
131
|
|
|
198
|
-
[
|
|
132
|
+
[The candidates that overlap this plan's surfaces. **If** none → `None`. Initially set to `PENDING`.]
|
|
199
133
|
|
|
200
134
|
<!-- prettier-ignore -->
|
|
201
135
|
| Candidate | Source | Overlaps | Recommendation |
|
|
202
136
|
| --- | --- | --- | --- |
|
|
203
|
-
| [what it is] | [`#N
|
|
204
|
-
|
|
205
|
-
> [!CAUTION]
|
|
206
|
-
> **Candidates, not scope.** Human review only — not runbook tasks, must not expand scope. Fold in only on design scope or explicit human decision → becomes task, leaves list.
|
|
137
|
+
| [what it is] | [`#N`, `docs/deferrals.jsonl`, `docs/failures.jsonl` or an audit finding id] | [the surface or task it touches] | [fold in, keep deferred, or needs a design decision] |
|
|
207
138
|
|
|
208
139
|
## Security & Privacy
|
|
209
140
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
- [ ] **
|
|
213
|
-
- [ ] **
|
|
214
|
-
- [ ] **
|
|
215
|
-
- [ ] **
|
|
216
|
-
- [ ] **
|
|
217
|
-
- [ ] **
|
|
218
|
-
- [ ] **Webhook** — signature verified? Secret declared in the env schema?
|
|
219
|
-
- [ ] **New Secret/Env Var** — added to the env schema? Stored in the project's secret manager (e.g. GCP Secret Manager / Vercel env)?
|
|
141
|
+
- [ ] **New API Route** — an auth guard (e.g., a `requireMember`-style check). **If** the route is auth-adjacent → a rate limit as well.
|
|
142
|
+
- [ ] **New DB Table/Column** — a deny-by-default row or tenant access policy (e.g., a row-level policy in the database), scoped to the tenant.
|
|
143
|
+
- [ ] **Role-Gated Mutation** — the role is checked at the API layer.
|
|
144
|
+
- [ ] **User Input** — validated against a schema in the handler (e.g., the schema library's parse call).
|
|
145
|
+
- [ ] **PII** — kept out of logs, and the audit or CDC trigger is updated for new monitored columns.
|
|
146
|
+
- [ ] **Redirect URL** — validated against an allow-list.
|
|
147
|
+
- [ ] **Webhook** — the signature is verified, and the secret is in the env schema.
|
|
148
|
+
- [ ] **New Secret/Env Var** — in the env schema and in the project's secret manager.
|
|
220
149
|
|
|
221
|
-
|
|
150
|
+
[**If** no row applies → write "None — no new routes, DB writes, secrets, or user input."]
|
|
222
151
|
|
|
223
152
|
## Pre-Flight / Dependencies
|
|
224
153
|
|
|
225
|
-
**CRITICAL:** Check off all core items. Check conditional items only when applicable. Abort if anything required is missing.
|
|
226
|
-
|
|
227
154
|
### Core
|
|
228
155
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
- [ ] **
|
|
232
|
-
- [ ] **
|
|
233
|
-
- [ ] **
|
|
234
|
-
- [ ] **
|
|
235
|
-
- [ ] **
|
|
236
|
-
- [ ] **Testing & Quality:** Ensure testing strategy aligns with `docs/testing.md`.
|
|
237
|
-
- [ ] **Prerequisite Plans:** List `docs/plans/...` plans that must be fully executed and verified before this one.
|
|
156
|
+
- [ ] **Package Management:** the packages are declared, and the manifest and lockfile are in sync.
|
|
157
|
+
- [ ] **Dependency Versions:** outdated dependencies and the toolchain and stack CLI versions are checked.
|
|
158
|
+
- [ ] **Existing-Solution Search (reuse over duplicate):** the in-repo, dependency and ecosystem searches are recorded in `Reuse Inventory`.
|
|
159
|
+
- [ ] **User Context:** access to the files is confirmed, and missing user information is requested.
|
|
160
|
+
- [ ] **Project Context:** the relevant `docs/knowledge.jsonl` and `docs/decisions.jsonl` rows are read.
|
|
161
|
+
- [ ] **Testing & Quality:** the testing strategy matches `docs/testing.md`.
|
|
162
|
+
- [ ] **Prerequisite Plans:** [the plans to finish first. **If** none → `None`.]
|
|
238
163
|
|
|
239
164
|
### Conditional
|
|
240
165
|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
- [ ] **
|
|
244
|
-
- [ ] **
|
|
245
|
-
- [ ] **
|
|
246
|
-
- [ ] **Observability:** New logs / audit tables / traces → align with `docs/observability.md` (e.g. structured logger calls, correlation IDs, CDC / OTel).
|
|
247
|
-
- [ ] **Notifications:** Alerts / toasts → notifications doc via `.agents/docs.md` for tier (e.g. 1=inline, 2=toast, 3=bell).
|
|
166
|
+
- [ ] **Secrets & Env Vars:** the secret store and the service-account roles are checked.
|
|
167
|
+
- [ ] **Schema State:** the database state is confirmed against `docs/data-schema.md`.
|
|
168
|
+
- [ ] **Architecture & UI:** the topology is checked against `docs/architecture.md`, and any UI against `docs/design.md`.
|
|
169
|
+
- [ ] **Observability:** logs, audit tables and traces follow `docs/observability.md`.
|
|
170
|
+
- [ ] **Notifications:** the alert or toast tier follows the notifications doc.
|
|
248
171
|
|
|
249
172
|
### 🔒 Gate 1: Prerequisites Check
|
|
250
173
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
- [ ] **
|
|
254
|
-
- [ ] **
|
|
255
|
-
- [ ] **
|
|
256
|
-
- [ ] **
|
|
257
|
-
- [ ] **
|
|
258
|
-
- [ ] **Gate 1 - Verified:** All Core items checked. All applicable Conditional items checked.
|
|
174
|
+
- [ ] **Acceptance Scenario confirmed:** the `👤 ⚠️ Acceptance Scenario` checkbox is `[x]`, ticked by a human.
|
|
175
|
+
- [ ] **Breaking Changes confirmed:** the `👤 ⚠️ Breaking Changes & Naming Review` checkbox is `[x]`, ticked by a human.
|
|
176
|
+
- [ ] **Open Questions confirmed:** the `👤 ⚠️ Open Questions & Assumptions` checkbox is `[x]`, ticked by a human.
|
|
177
|
+
- [ ] **Security & Privacy checked:** every applicable row is verified, or `None` is justified.
|
|
178
|
+
- [ ] **Reuse Inventory complete:** every capability has a row with `Search performed` and `Decision` filled in.
|
|
179
|
+
- [ ] **Reuse reasons:** every `NEW` row cites its reason.
|
|
180
|
+
- [ ] **Gate 1 — Verified:** every item above, every Core item and every applicable Conditional item is checked.
|
|
259
181
|
|
|
260
182
|
## Data Schema Integration
|
|
261
183
|
|
|
262
|
-
[
|
|
263
|
-
|
|
264
|
-
**Invariant Conformance:** Multi-store or privileged writes → every mutation path maintains every store a read surface depends on, under a compatible privilege, with the returned error actually checked (never swallowed). If a write can fail on privilege/constraint, the plan says how that failure surfaces — not a silent 200.
|
|
184
|
+
[How this feature uses the existing schema, and what changes. Initially set to `PENDING`.]
|
|
265
185
|
|
|
266
186
|
### Data Schema Usage
|
|
267
187
|
|
|
268
|
-
[
|
|
188
|
+
[The existing `docs/data-schema.md` tables and fields the feature reads (Input) or writes (Output). **If** none → `None`. Initially set to `PENDING`.]
|
|
269
189
|
|
|
270
|
-
- **Input (Read):** `users.id`, `items.title`
|
|
271
|
-
- **Output (Write):** `items.status`, `job_audits.log`]
|
|
272
|
-
If no existing fields are used, explicitly state "None".
|
|
190
|
+
- [e.g., **Input (Read):** `users.id`, `items.title`]
|
|
191
|
+
- [e.g., **Output (Write):** `items.status`, `job_audits.log`]
|
|
273
192
|
|
|
274
193
|
### Data Schema Changes
|
|
275
194
|
|
|
276
|
-
[
|
|
195
|
+
[The new tables, new fields and changed fields to record in `docs/data-schema.md`. **If** none → `None`. Initially set to `PENDING`.]
|
|
277
196
|
|
|
278
|
-
- **ADD:** `items.new_field` (type: text)
|
|
279
|
-
- **MODIFY:** `users.role` (added enum value)]
|
|
280
|
-
If no schema changes are required, explicitly state "None".
|
|
197
|
+
- [e.g., **ADD:** `items.new_field` (type: text)]
|
|
198
|
+
- [e.g., **MODIFY:** `users.role` (added enum value)]
|
|
281
199
|
|
|
282
200
|
## Reuse Inventory
|
|
283
201
|
|
|
284
|
-
[One row per capability plan introduces
|
|
202
|
+
[One row per capability the plan introduces. Initially set to `PENDING`.]
|
|
285
203
|
|
|
286
204
|
<!-- prettier-ignore -->
|
|
287
|
-
| Capability | Search performed | Existing candidates | Decision | Justification |
|
|
288
|
-
| --- | --- | --- | --- | --- |
|
|
289
|
-
| [what the plan must do] | `grep -rn "..."
|
|
290
|
-
| [
|
|
291
|
-
|
|
292
|
-
> [!CAUTION]
|
|
293
|
-
> **Default = `EXTEND`.** `NEW` only allowed for:
|
|
294
|
-
> (a) no candidate — `Search performed` shows the commands establishing absence;
|
|
295
|
-
> (b) extending breaks the candidate's contract or callers — name both;
|
|
296
|
-
> (c) candidate is a `Supersession Inventory` `DELETE` — replacement, not duplicate.
|
|
297
|
-
>
|
|
298
|
-
> never accept cleaner-fresh / messy-existing / close-but-different as a `NEW` reason — messy candidate → extend and clean it, in scope. Empty `Search performed` = UNSEARCHED, not `NEW`-eligible.
|
|
299
|
-
>
|
|
300
|
-
> Each `EXTEND` row must land as `[MODIFY] path/to/existing` in `Architecture & Component Changes` and a task in `Agent Execution Runbook`; each `NEW` row as `[NEW]` carrying the same reason. `[NEW]` with no row = unjustified.
|
|
205
|
+
| Capability | File | Search performed | Existing candidates | Decision | Justification |
|
|
206
|
+
| --- | --- | --- | --- | --- | --- |
|
|
207
|
+
| [what the plan must do] | `path/to/existing` | `grep -rn "..."`, references to `{symbol}`, `docs/capabilities.md`, `{framework} {capability} built-in` | `path/to/existing` — covers [X], missing [Y] | EXTEND | [what changes in it to close the gap] |
|
|
208
|
+
| [e.g., item status column] | `packages/db/migrations/{timestamp}_add_items_status.sql` | [the exact commands and queries run] | None — [what was searched] | NEW | [reason (a), (b) or (c)] |
|
|
209
|
+
| [e.g., status change action] | `packages/api/src/items/setStatus.ts` | [the exact commands and queries run] | None — [what was searched] | NEW | [reason (a), (b) or (c)] |
|
|
301
210
|
|
|
302
211
|
## Architecture & Component Changes
|
|
303
212
|
|
|
304
|
-
[
|
|
305
|
-
**
|
|
306
|
-
**CRITICAL:** Prefer `[MODIFY]` over `[NEW]`. Every `[NEW]` must trace to a `Reuse Inventory` `NEW` row and carry its reason — no parallel reimplementation. Superseded → `Supersession Inventory` as `DELETE`.
|
|
307
|
-
**CRITICAL:** Frontend/Mobile → adhere to `docs/design.md`.
|
|
308
|
-
**CRITICAL:** Verify `[MODIFY]` files exist (else `[NEW]`). Before changing exported symbol/signature/contract: find callers/importers/schemas/consumers (language-server references when configured + text search), list blast radius.
|
|
309
|
-
**CRITICAL:** Include backend actions for new schema validations (e.g. Zod `schema.parse`).
|
|
310
|
-
**CRITICAL:** NEVER weaken gate to pass: no type-system escapes (e.g. TS `as any` / `as unknown as` / `@ts-ignore`, Python `# type: ignore`), linter disables (e.g. `eslint-disable`, `//nolint`), test skips (e.g. `.skip`, `xfail`), deleted assertions, empty `catch` / error-swallowing, mocking-away unit under test. Fix root causes; per-file opt-out needs explicit human sign-off.
|
|
311
|
-
**CRITICAL:** Auto-capture (e.g. log drains / CDC) does not replace explicit logging — log edge cases escaping auto-capture with the project's structured logger (e.g. `console.error("[Context] Message", payload)`). See `docs/observability.md` for naming, severity, correlation IDs, label taxonomy.
|
|
213
|
+
[The files, grouped by area (DB, API, Backend, Frontend, Cron, Observability), with one heading per area. Initially set to `PENDING`.]
|
|
214
|
+
**Ledger rows:** [The backticked `key` of every `docs/decisions.jsonl` and `docs/deferrals.jsonl` row written for this plan, comma-separated. **If** none → write "None". Initially set to `PENDING`.]
|
|
312
215
|
|
|
313
216
|
### Database Migrations
|
|
314
217
|
|
|
315
|
-
[
|
|
316
|
-
|
|
317
|
-
> [!WARNING]
|
|
318
|
-
> **If adding/removing columns on CDC/audit-monitored tables (e.g. `users` and the other tenant tables your project monitors):**
|
|
319
|
-
>
|
|
320
|
-
> 1. Update the monitored-column allow-list in the schema-assurance test (e.g. a `knownSafeColumns` list).
|
|
321
|
-
> 2. If a column contains PII → update the audit trigger to scrub it.
|
|
322
|
-
> 3. See `docs/data-schema.md` for the full checklist.
|
|
218
|
+
[The new tables, columns and access policies (e.g., row-level policies), and the migration that adds them. Initially set to `PENDING`.]
|
|
323
219
|
|
|
324
220
|
### [Component Area 1]
|
|
325
221
|
|
|
326
|
-
[
|
|
222
|
+
[A summary of the component changes. Initially set to `PENDING`.]
|
|
327
223
|
|
|
328
224
|
#### [MODIFY] `path/to/file.ext`
|
|
329
225
|
|
|
330
|
-
- **Existence Check:** [
|
|
331
|
-
- [
|
|
226
|
+
- **Existence Check:** [the file exists]
|
|
227
|
+
- [The logic, schema or API contract changes.]
|
|
332
228
|
|
|
333
229
|
#### [new] `path/to/file.ext`
|
|
334
230
|
|
|
335
|
-
- **Reuse Check:** [`Reuse Inventory` row
|
|
336
|
-
- [
|
|
231
|
+
- **Reuse Check:** [the `Reuse Inventory` row, and reason (a), (b) or (c)]
|
|
232
|
+
- [The purpose, access policies, input validation and naming.]
|
|
337
233
|
|
|
338
234
|
#### [DELETE] `path/to/file.ext`
|
|
339
235
|
|
|
340
|
-
- [
|
|
236
|
+
- [The reason]
|
|
341
237
|
|
|
342
238
|
### Cron Jobs & Scheduled Tasks
|
|
343
239
|
|
|
344
|
-
[
|
|
240
|
+
[The scheduled tasks (e.g., a hosting platform's cron, a database scheduler or a background-job runner). **If** none → `None`. Initially set to `PENDING`.]
|
|
345
241
|
|
|
346
242
|
## Supersession Inventory
|
|
347
243
|
|
|
348
|
-
[
|
|
244
|
+
[The existing artifacts the new code replaces. **If** none → `None`. Initially set to `PENDING`.]
|
|
349
245
|
|
|
350
246
|
<!-- prettier-ignore -->
|
|
351
247
|
| Existing artifact | Replaced by | Decision | Justification |
|
|
352
248
|
| --- | --- | --- | --- |
|
|
353
|
-
| `path/to/old-thing` | `path/to/new-thing` | DELETE | [reason] |
|
|
354
|
-
|
|
355
|
-
> [!CAUTION]
|
|
356
|
-
> **Default = `DELETE`.** `RETAIN-WITH-REASON` only allowed for:
|
|
357
|
-
> (a) external contract — atomic migration impossible (third-party callers, public API);
|
|
358
|
-
> (b) staged rollout with kill-date and follow-up issue link.
|
|
359
|
-
>
|
|
360
|
-
> never accept `@deprecated` and still exported as a resolution. Each `DELETE` row must be mirrored as `[DELETE] path/to/file` in `Architecture & Component Changes` and as a removal task in `Agent Execution Runbook`.
|
|
249
|
+
| `path/to/old-thing` | `path/to/new-thing` | DELETE | [the reason] |
|
|
361
250
|
|
|
362
251
|
## Documentation Updates
|
|
363
252
|
|
|
364
|
-
|
|
253
|
+
[One row per doc this change touches. Find any doc not listed here through `.agents/docs.md`.]
|
|
365
254
|
|
|
366
255
|
<!-- prettier-ignore -->
|
|
367
256
|
| Doc | Change required |
|
|
368
257
|
| --- | --- |
|
|
369
|
-
| `docs/knowledge.jsonl` | [learnings
|
|
258
|
+
| `docs/knowledge.jsonl` | [learnings and gotchas] |
|
|
370
259
|
| `docs/decisions.jsonl` | [architecture decisions] |
|
|
371
|
-
| `docs/architecture.md` | [topology
|
|
372
|
-
| `docs/technology.md` | [frameworks, libraries
|
|
373
|
-
| `docs/data-schema.md` | [new tables
|
|
374
|
-
| `docs/design.md` | [palette, typography
|
|
375
|
-
| `docs/testing.md` | [new test files
|
|
376
|
-
| `docs/observability.md` | [new log names
|
|
377
|
-
|
|
378
|
-
_Delete rows with no change; add a row per other affected doc (resolve via `.agents/docs.md`)._
|
|
260
|
+
| `docs/architecture.md` | [topology or component changes] |
|
|
261
|
+
| `docs/technology.md` | [frameworks, libraries and conventions] |
|
|
262
|
+
| `docs/data-schema.md` | [new tables or columns] |
|
|
263
|
+
| `docs/design.md` | [palette, typography and components] |
|
|
264
|
+
| `docs/testing.md` | [new test files or patterns] |
|
|
265
|
+
| `docs/observability.md` | [new log names or spans] |
|
|
379
266
|
|
|
380
267
|
## Rollback Strategy
|
|
381
268
|
|
|
382
269
|
<!-- prettier-ignore -->
|
|
383
270
|
| Axis | Action | Notes |
|
|
384
271
|
| --- | --- | --- |
|
|
385
|
-
| **DB** | [
|
|
386
|
-
| **Code** | [
|
|
387
|
-
| **Risk window** | [
|
|
272
|
+
| **DB** | [A corrective migration that undoes the change. It is safe when the change only adds.] | Merged migrations are immutable, so ship the corrective migration through CI's migration lane. For a full dev reset, see `docs/deployments.md` § Dev rollback runbook. |
|
|
273
|
+
| **Code** | [The git revert SHA, or the feature flag that disables the change] | `git revert {COMMIT}` |
|
|
274
|
+
| **Risk window** | [The gap between the DB migration merge and the code deploy] | [e.g., "~2 min deploy build, so the migration must be additive"] |
|
|
388
275
|
|
|
389
|
-
|
|
276
|
+
[**If** there are no DB changes → write "Code-only — `git revert` sufficient."]
|
|
390
277
|
|
|
391
278
|
## Agent Execution Runbook
|
|
392
279
|
|
|
393
|
-
[
|
|
394
|
-
|
|
395
|
-
> [!IMPORTANT]
|
|
396
|
-
> **Continuous Execution:** Run runbook autonomously; no user permission at Gates; `[x]` as you go.
|
|
397
|
-
> **Step Isolation:** Finish task (verify + checkbox) before next.
|
|
398
|
-
> **Integration Shape:** may suggest PR / commit / sequencing — advisory, never a gate; one PR for all tasks always OK. Do not specify merge method.
|
|
280
|
+
[A chronological task checklist. Initially set to `PENDING`.]
|
|
399
281
|
|
|
400
282
|
**Implementation Tasks (Examples):**
|
|
401
283
|
|
|
402
|
-
|
|
403
|
-
>
|
|
404
|
-
> **Tests ship with their task.** Task adding / changing logic → names its own unit tests in `Done when`, matrix row or not; tests it breaks → fixed in same task. never defer task tests to later tasks to avoid splits that leave untested code and drop coverage gates.
|
|
405
|
-
>
|
|
406
|
-
> **Build order and test source.** Order tasks by build dependency (schema → API → UI). Behaviour tests only from `Derived Test Matrix` rows — do not invent. Boundary-crossing tasks (DB / API / model / network / migration) carry paired non-mock `Done when` tests; pure-function tasks exempt from pairing, not from unit tests.
|
|
407
|
-
>
|
|
408
|
-
> **Test first.** Every task MUST include `**Test first:**` after `Done when`. Behaviour change at unit / integration tier → one or more tests, `;`-separated, each `` `{test file}` `` `` `{test name}` `` fails on {assertion} — repo-relative test files, test names as the runner reports them or their last segments, no `;` in assertion text; build sees each fail against stubs before writing the task's code. No behaviour change (docs, config, pure refactor) or E2E / `@live` tier only → `n/a — {reason naming which}`.
|
|
409
|
-
>
|
|
410
|
-
> **Issue tasks.** Change-shape issue (`.bkit/trackers.md` § Issue shapes) → its `Tasks` lines are the starting runbook; keep each `Done when` / `Test first` (tighten, never weaken); renumber in build order.
|
|
284
|
+
<!-- bkit:group 1 start -->
|
|
411
285
|
|
|
412
|
-
|
|
413
|
-
- [ ] **Task 2:** [e.g., Implement backend API action `action.ts`]. **Done when:** [e.g., `packages/api/src/items/setStatus.ts` exports `setStatus` with Zod-validated input; unit test `packages/api/src/items/setStatus.test.ts` covers each status transition; integration test in `packages/api/items.integration.test.ts` passes]. **Test first:** [e.g., `packages/api/src/items/setStatus.test.ts` `rejects an unknown status` fails on the thrown validation error — stub accepts any status; `packages/api/items.integration.test.ts` `persists the new status` fails on the stored row — stub writes nothing].
|
|
414
|
-
- [ ] **Task 3:** [e.g., Update React component `page.tsx`]. **Done when:** [e.g., `apps/web/app/items/page.tsx` renders status badge; Playwright spec `apps/web/e2e/items.spec.ts` confirms user-visible state]. **Test first:** [e.g., n/a — E2E tier only; runs in CI].
|
|
286
|
+
### TASK GROUP 1: [e.g., Item status in the API]
|
|
415
287
|
|
|
416
|
-
|
|
288
|
+
<!-- bkit:task 1 start -->
|
|
417
289
|
|
|
418
|
-
|
|
290
|
+
- [ ] **TASK 1:** [e.g., Create the database migration with the repo's migration script (`pnpm db:diff`)]
|
|
291
|
+
- **CREATE:** `packages/db/migrations/{timestamp}_add_items_status.sql`: [e.g., the `items.status` column]
|
|
292
|
+
- **DONE WHEN:** [e.g., the migration exists, and `pnpm db:reset` replays it cleanly]
|
|
293
|
+
- **TEST FIRST:** n/a — [e.g., a migration, covered by the fresh-DB replay tier]
|
|
419
294
|
|
|
420
|
-
|
|
421
|
-
- [ ] **Test first:** every task naming `Test first` tests recorded a red per test before its code; tests unchanged since except added tests / formatting.
|
|
422
|
-
- [ ] **Gate 2 - Verified:** Every checkbox above independently verified and checked off against the plan.
|
|
295
|
+
<!-- bkit:task 1 end -->
|
|
423
296
|
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
297
|
+
<!-- bkit:task 2 start -->
|
|
298
|
+
|
|
299
|
+
- [ ] **TASK 2:** [e.g., Implement the backend API action `setStatus`]
|
|
300
|
+
- **CREATE:** `setStatus` in `packages/api/src/items/setStatus.ts`: [e.g., a validated status change]
|
|
301
|
+
- **READ:** `ItemStatus` in `packages/api/src/items/schema.ts`: [e.g., the allowed statuses]
|
|
302
|
+
- **DEPENDS ON:** 1
|
|
303
|
+
- **DONE WHEN:** [e.g., a unit test covers each status transition, and the integration test passes]
|
|
304
|
+
- **TEST FIRST:**
|
|
305
|
+
- `packages/api/src/items/setStatus.test.ts` `rejects an unknown status` fails on [e.g., an unknown status being accepted]
|
|
306
|
+
- `packages/api/items.integration.test.ts` `persists the new status` fails on [e.g., no row being stored]
|
|
307
|
+
|
|
308
|
+
<!-- bkit:task 2 end -->
|
|
309
|
+
|
|
310
|
+
<!-- bkit:group 1 end -->
|
|
311
|
+
|
|
312
|
+
### 🔒 Gate 2: Code Implementation Check
|
|
313
|
+
|
|
314
|
+
- [ ] **No bolt-on:** every `[NEW]` file traces to a `Reuse Inventory` `NEW` row.
|
|
315
|
+
- [ ] **Extensions landed:** every `EXTEND` landed in the artifact its row names.
|
|
316
|
+
- [ ] **No gate weakened:** no gate was weakened.
|
|
317
|
+
- [ ] **Red before code:** the tests step recorded every planned test of the group red, or as an `updated` existing test, before its code step ran.
|
|
318
|
+
- [ ] **Tests unchanged:** every planned test case matches the lines its red row recorded.
|
|
319
|
+
- [ ] **Unproven tests:** each planned test with no proven red is cleared only by a human-committed `TEST EXCEPTION` field.
|
|
320
|
+
- [ ] **Gate 2 — Verified:** every box above is checked.
|
|
432
321
|
|
|
433
322
|
**Mandatory Tasks (Testing & Documentation):**
|
|
434
323
|
|
|
435
|
-
- [ ] **Verify test coverage against Derived Test Matrix:**
|
|
436
|
-
- [ ] **Sweep existing tests:**
|
|
437
|
-
- [ ] **Sweep new tests:**
|
|
438
|
-
- [ ] **Verify observability:**
|
|
439
|
-
- [ ] **Update documentation:**
|
|
324
|
+
- [ ] **Verify test coverage against Derived Test Matrix:** each row's test is in one task's `DONE WHEN`.
|
|
325
|
+
- [ ] **Sweep existing tests:** broken tests are fixed, and the full suite passes.
|
|
326
|
+
- [ ] **Sweep new tests:** every test a task's `DONE WHEN` names exists and passes.
|
|
327
|
+
- [ ] **Verify observability:** errors are logged and traced as `docs/observability.md` describes.
|
|
328
|
+
- [ ] **Update documentation:** the affected docs are rewritten to match.
|
|
440
329
|
|
|
441
330
|
### 🔒 Gate 3: Testing & Documentation Check
|
|
442
331
|
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
- [ ] **
|
|
446
|
-
- [ ] **Gate 3 - Verified:** Every checkbox above independently verified and checked off.
|
|
332
|
+
- [ ] **Docs updated:** every `Documentation Updates` row is done.
|
|
333
|
+
- [ ] **Docs index accurate:** `.agents/docs.md` is accurate.
|
|
334
|
+
- [ ] **Gate 3 — Verified:** every box above is checked.
|
|
447
335
|
|
|
448
336
|
## Verification Plan
|
|
449
337
|
|
|
450
|
-
> [!IMPORTANT]
|
|
451
|
-
> **Advisory build-phase checks, not merge gates.** Only `Agent Execution Runbook` `Done when` lines gate merge; nothing here does. Do not write "before merge" on untickable boxes — CI/human-only preconditions (lane RUN, deployed state, operator step) unenforceable. Work that MUST block merge → runbook task + codebase-verifiable `Done when`; lane that must run → CI config, not plan prose.
|
|
452
|
-
|
|
453
338
|
### Automated Tests
|
|
454
339
|
|
|
455
|
-
- [ ] **Full Local Gate Suite:**
|
|
456
|
-
- [ ] **Test Synchronization:** [
|
|
457
|
-
- [ ] **Build Configuration:** [
|
|
458
|
-
- [ ] **[Test Type] (`path/to/test.spec.ts`):** [
|
|
459
|
-
- [ ] **Apply local migrations:**
|
|
460
|
-
- [ ] **Run all tests:**
|
|
461
|
-
|
|
462
|
-
> [!IMPORTANT]
|
|
463
|
-
> **No Architectural Downgrades:** Build / compiler / test errors during verification → never hot-fix or anti-pattern; follow `docs/architecture.md` + named reference repos. Halt if stuck.
|
|
340
|
+
- [ ] **Full Local Gate Suite:** the deepest declared `bkit:gate:*` script and `bkit check` pass.
|
|
341
|
+
- [ ] **Test Synchronization:** [The existing E2E tests to update alongside.]
|
|
342
|
+
- [ ] **Build Configuration:** [How test-only files are kept out of the production build (e.g., the compiler config's exclude list).]
|
|
343
|
+
- [ ] **[Test Type] (`path/to/test.spec.ts`):** [The flow, unit or E2E additions, and their data hygiene needs.]
|
|
344
|
+
- [ ] **Apply local migrations:** [The new migrations applied locally (e.g., `pnpm db:reset`).]
|
|
345
|
+
- [ ] **Run all tests:** [The local unit and integration suites (e.g., `pnpm test`, `pnpm test:integration`) pass.]
|
|
464
346
|
|
|
465
347
|
### 🔒 Gate 4: Automated Verification Check
|
|
466
348
|
|
|
467
|
-
**
|
|
349
|
+
- [ ] **Gate 4 — Verified:** every Automated Tests box is checked, with proof (test output, a CLI result or an API response).
|
|
468
350
|
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
### 👤 Manual Verification
|
|
351
|
+
### Manual Verification
|
|
472
352
|
|
|
473
353
|
> [!CAUTION]
|
|
474
|
-
> **Owner-run acceptance checks
|
|
475
|
-
|
|
476
|
-
> [!WARNING]
|
|
477
|
-
> **Dashboard Ban:** Proactively use local CLIs (e.g. `gh`, `vercel`, `npx supabase`) to verify CI/CD pipelines instead of asking users to check dashboards.
|
|
354
|
+
> **Owner-run acceptance checks, advisory only.** An unticked box blocks nothing: not the merge, and not plan approval. This is not a Gate 1 human-confirmation section.
|
|
478
355
|
|
|
479
|
-
- [ ] **Step 1:** [
|
|
356
|
+
- [ ] **Step 1:** [How to verify the feature end to end through the CLI or the database.]
|
|
480
357
|
|
|
481
358
|
<!-- bkit:end -->
|