@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
|
@@ -3,141 +3,228 @@
|
|
|
3
3
|
{{BKIT_MANAGED_MARKER}}
|
|
4
4
|
|
|
5
5
|
> [!CAUTION]
|
|
6
|
-
> **Purpose:** How to format a new row for any bkit JSONL ledger (`docs/deferrals.jsonl`, `docs/failures.jsonl`, `docs/knowledge.jsonl`, `docs/decisions.jsonl`, `.bkit/issues.jsonl`, `.bkit/friction.jsonl`, `.bkit/stats.jsonl`).
|
|
6
|
+
> **Purpose:** How to format a new row for any bkit JSONL ledger (`docs/deferrals.jsonl`, `docs/failures.jsonl`, `docs/knowledge.jsonl`, `docs/decisions.jsonl`, `.bkit/issues.jsonl`, `.bkit/friction.jsonl`, `.bkit/stats.jsonl`). The codec is `.bkit/core/engine/ledgers/telemetry.ts`. Which `kind` goes to which ledger, and when each workflow writes it, is in `.bkit/workflows.md` § Telemetry Ledgers.
|
|
7
7
|
>
|
|
8
8
|
> **Rules:**
|
|
9
9
|
>
|
|
10
|
-
> -
|
|
11
|
-
> -
|
|
12
|
-
> -
|
|
13
|
-
> -
|
|
14
|
-
> -
|
|
15
|
-
> -
|
|
16
|
-
> -
|
|
10
|
+
> - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit this file.
|
|
11
|
+
> - This file ships to every project that installs bkit. Describe the current setup only.
|
|
12
|
+
> - Leave out internal labels, such as tracker issue numbers, ledger keys and review-finding ids, and leave out project history. Decisions go in `docs/decisions.jsonl`, and incidents go in `docs/knowledge.jsonl`.
|
|
13
|
+
> - Write one row per line.
|
|
14
|
+
> - NEVER edit, reorder or delete a prior line. Change a row through a same-`key` append (§ Updating a Row). The only exceptions are the `bkit install` / `bkit upgrade` schema migration (§ Versioning), `bkit ledgers compact` (§ Compaction), and bkit's harvest (`pnpm harvest`, bkit repo only), which prunes a `.bkit/friction.jsonl` row or a `chat` / `run` row of `.bkit/stats.jsonl` only after the exact row is stored in `harvest/` and read back, and never prunes a malformed line (§ Friction Is a Drained Queue).
|
|
15
|
+
> - Before you append, read the file. Skip the append only if a row with the same identity exists and nothing has changed. A changed field makes the new row an update, not a duplicate.
|
|
16
|
+
> - Appends are best-effort: always exit 0. Never gate a workflow on telemetry success.
|
|
17
|
+
|
|
18
|
+
## Read Idiom
|
|
19
|
+
|
|
20
|
+
**Engine readers:** `normalize()` and `fold()` in `.bkit/core/engine/ledgers/telemetry.ts` handle older schemas and current-state reads across all telemetry kinds.
|
|
21
|
+
|
|
22
|
+
- **Identity:** Group by § Identity / Dedup. A bare `key` suffices only within one keyed kind and one repo.
|
|
23
|
+
- **Winner:** Keep the highest numeric `ts` per identity; the later line wins a tie.
|
|
24
|
+
- **Filters:** Apply status and query filters after folding, so superseded rows stay superseded. Decisions / knowledge default to `ACTIVE`; open failures / deferrals include `TRIAGED` and exclude `CLOSED` (§ Updating a Row).
|
|
25
|
+
- **History:** Retain the rows needed for the requested time range instead of reducing them to current state.
|
|
26
|
+
- **Workflow logs:** Read `status.jsonl` through the workflow's status commands. These are event histories with their own replay rules, outside this fold.
|
|
27
|
+
|
|
28
|
+
**Humans and scripts:** This Python example folds decisions and knowledge separately, each containing one keyed kind from one repo, then prints active rows. Run from the repo root; output is stdout only.
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
import json
|
|
32
|
+
import math
|
|
33
|
+
from pathlib import Path
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def latest_rows(records):
|
|
37
|
+
latest = {}
|
|
38
|
+
for row in records:
|
|
39
|
+
key, timestamp = row["key"], row["ts"]
|
|
40
|
+
if not isinstance(key, str) or not key:
|
|
41
|
+
raise ValueError("Ledger key must be a nonempty string")
|
|
42
|
+
if isinstance(timestamp, bool) or not isinstance(timestamp, (int, float)) or not math.isfinite(timestamp):
|
|
43
|
+
raise ValueError("Ledger ts must be a finite number")
|
|
44
|
+
previous = latest.get(key)
|
|
45
|
+
if previous is None or timestamp >= previous["ts"]:
|
|
46
|
+
latest[key] = row
|
|
47
|
+
return latest
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
for name in ["decisions", "knowledge"]:
|
|
51
|
+
records = [json.loads(line) for line in Path(f"docs/{name}.jsonl").read_text().splitlines() if line.strip()]
|
|
52
|
+
for row in latest_rows(records).values():
|
|
53
|
+
if row.get("status", "ACTIVE") == "ACTIVE":
|
|
54
|
+
print(json.dumps(row))
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
- **First row:** Handle a new identity separately; never compare its numeric `ts` with a string default.
|
|
58
|
+
- **Failures:** Report missing files, invalid JSON and invalid `key` / `ts` fields as read failures, not empty results.
|
|
17
59
|
|
|
18
60
|
## Write Idiom
|
|
19
61
|
|
|
62
|
+
**Engine and workflow writers:** `bkit ledgers append --ledger=<decisions|deferrals|failures|knowledge|friction|stats> --rows=<file|->`. The rows are a JSON array without `schema` / `ts` / `bkit`.
|
|
63
|
+
|
|
64
|
+
- **Fills:** `schema: 3`, a minted `ts` per row, `repo` when absent, and `bkit.version` from `.bkit/version`. On `deferral` / `failure` / `knowledge` / `decision` rows, it also fills `firstTs` and `updates` from the entry's earlier rows (§ Compaction), replacing any supplied values.
|
|
65
|
+
- **Checks** every row before writing any: validation, and the author against § Ledgers & Writers. One refused row → exit 8, and nothing is written.
|
|
66
|
+
- **Refused:** a supplied `schema` / `ts` / `bkit`; a flat `bkitVersion` / `workflow` / `step` / `subagent` / `model`, since those live in `bkit` / `by`; a kind the ledger does not take; and a total that does not match its parts.
|
|
67
|
+
- `--ledger=stats` takes `compliance` / `counter` / `outcome` rows. `bkit workflows close` writes through it.
|
|
68
|
+
- A subagent with no shell hands its rows to the orchestrator as that JSON, with `by.subagent` and `by.model` already set.
|
|
69
|
+
- `bkit roadmap feature` writes `feature` rows, and fills `firstTs` and `updates` the same way. A `--row` that already carries `updates` (a row an earlier call printed) is appended byte for byte. bkit's harvest script writes `chat` / `run` rows, into `harvest/stats.jsonl` only.
|
|
70
|
+
|
|
71
|
+
**Humans and scripts:** the `jq` idiom:
|
|
72
|
+
|
|
20
73
|
```bash
|
|
21
|
-
jq -c -n '{ ts: null, kind: "deferral", repo: $REPO,
|
|
74
|
+
jq -c -n '{ schema: 3, ts: null, kind: "deferral", repo: $REPO, bkit: { version: $VER }, by: { step: $STEP }, … } | .ts = (now*1000|floor)' \
|
|
22
75
|
>> "$FILE" || echo "[bkit-telemetry] append failed: $FILE"
|
|
23
76
|
```
|
|
24
77
|
|
|
25
|
-
- **`ts`:** Unix ms, always minted by `jq`'s `now`
|
|
26
|
-
- **`ts` is never a literal.**
|
|
27
|
-
-
|
|
78
|
+
- **`ts`:** Unix ms, always minted by `jq`'s `now` at append time: `jq '… | .ts = (now*1000|floor)'`. The `ts: null` placeholder only holds the field's place in the order, and the pipe overwrites it. Without the pipe, the row fails validation instead of landing a fake value. Never seed the placeholder with a number.
|
|
79
|
+
- **`ts` is never a literal.** Do not hand-type it, copy it from an example row or the line above, or take it from `date +%s%3N`, which does not work on BSD / macOS. A fabricated past `ts` looks the same as a real one, and it silently reorders the last-wins fold that every reader, the harvest and every age report depend on. Whole-second values (`ts % 1000 == 0`) fail the live-ledger gate, because a real mint is never round: `bkit ledgers append` moves such a value 1 ms on, and a `jq` append that lands on one is re-run.
|
|
80
|
+
- **`firstTs` / `updates`:** Omit them. The next compaction stamps them (§ Compaction).
|
|
81
|
+
- **Log prefix:** Every telemetry log line starts with `[bkit-telemetry]`, because log-drain greps match on it.
|
|
28
82
|
|
|
29
83
|
## Ledgers & Writers
|
|
30
84
|
|
|
31
|
-
|
|
85
|
+
Each `kind` goes to one file. Its writers:
|
|
32
86
|
|
|
33
87
|
<!-- prettier-ignore -->
|
|
34
88
|
| Kind | File | Written by |
|
|
35
89
|
| --- | --- | --- |
|
|
36
|
-
| `compliance` | `.bkit/stats.jsonl` | `bkit
|
|
37
|
-
| `outcome` | `.bkit/stats.jsonl` |
|
|
38
|
-
| `counter` | `.bkit/stats.jsonl` |
|
|
39
|
-
| `
|
|
40
|
-
| `
|
|
90
|
+
| `compliance` | `.bkit/stats.jsonl` | `bkit workflows close` of design / plan / build / debug / ship (its grader, one row per rule); utility orchestrator (a direct chat outside any workflow, the owner deciding in it) |
|
|
91
|
+
| `outcome` | `.bkit/stats.jsonl` | `bkit workflows close` of design / plan / build / debug / ship (one row per workflow run, keyed by `repo`+`by.workflow`+`run.parentSha`); re-appended by the close's CI dispatch (§ Per-Kind Fields); utility orchestrator (a direct chat outside any workflow, the owner deciding in it) |
|
|
92
|
+
| `counter` | `.bkit/stats.jsonl` | `bkit workflows close` of design / plan / build / debug / ship (attempt counters); utility orchestrator (a direct chat outside any workflow, the owner deciding in it) |
|
|
93
|
+
| `chat` | `harvest/stats.jsonl` (bkit repo only) | bkit's harvest script: per agent chat on the maintainer's machine, any repo or host |
|
|
94
|
+
| `run` | `harvest/stats.jsonl` (bkit repo only) | Same script: per workflow run in the run logs of every repo a chat ran in |
|
|
95
|
+
| `friction` | `.bkit/friction.jsonl` | orchestrator workflows (design / plan / build / debug / ship / auto) on observed friction; utility orchestrator (a direct chat outside any workflow that meets friction); the engine itself, as the active workflow, on a bkit command's undeclared non-zero exit (`category: "tool-failure"`, `scope: "bkit-repo"`, in the active run's own book root; `BKIT_ENGINE_JOURNAL=off` disables it), and from `status row --type=owner-pause` on each owner pause (`category: "human-confirm"`, same book root and kill switch) |
|
|
96
|
+
| `deferral` | `docs/deferrals.jsonl` | `@bkit-design-generate`, `@bkit-plan-generate`, `@bkit-plan-update`, `@bkit-debug-abort-handover`, `@bkit-ship-deferred-sweep` (adjudication only), `@bkit-utility-update-deferrals` (close / triage / locator), build orchestrator (`LOW` challenge finding → `low-severity`, through `bkit challenge merge`), ship orchestrator (assumed accept nobody confirmed → `needs-decision`, through `bkit decisions pending --defer`), utility orchestrator (a direct chat outside any workflow, the owner deciding in it) |
|
|
41
97
|
| `failure` | `docs/failures.jsonl` | any agent on a discovered bug; `@bkit-debug-abort-handover`; `@bkit-audit-generate` (`MEDIUM`+ findings; rerun closes rows it no longer finds); `@bkit-utility-update-failures` (close / triage / locator) |
|
|
42
|
-
| `knowledge` | `docs/knowledge.jsonl` | `@bkit-build-
|
|
43
|
-
| `decision` | `docs/decisions.jsonl` | `@bkit-debug-failure-remediate` (forced arch), `@bkit-plan-generate`, `@bkit-utility-update-decisions` (supersede / correct) |
|
|
98
|
+
| `knowledge` | `docs/knowledge.jsonl` | `@bkit-build-plan-tests`, `@bkit-build-plan-tasks`, `@bkit-build-plan-gaps-remediate`, `@bkit-debug-failure-remediate` (after verified fix), `@bkit-utility-update-knowledge` (supersede / correct), utility orchestrator (a direct chat outside any workflow, the owner deciding in it) |
|
|
99
|
+
| `decision` | `docs/decisions.jsonl` | `@bkit-debug-failure-remediate` (forced arch), `@bkit-plan-generate`, `@bkit-plan-update` (decision changed by review), `@bkit-utility-update-decisions` (supersede / correct), build orchestrator (Decision Pause accept), design orchestrator (owner's answer to an open question after close), plan orchestrator (open question answered after close), ship orchestrator (assumed accept confirmed by the owner, through `bkit decisions apply --by=owner`), utility orchestrator (a direct chat outside any workflow, the owner deciding in it); orchestrators ONLY after explicit human approval |
|
|
44
100
|
| `feature` | `.bkit/issues.jsonl` | design / plan / build / debug orchestrators at their phase close; ship Step 6 into the worktree ledger (rides the PR); `ABANDONED` only by a human, or an agent on explicit human instruction |
|
|
45
101
|
|
|
46
|
-
**Writers are exhaustive:**
|
|
102
|
+
**Writers are exhaustive:** Only the agents listed as writers for a kind may write that kind, with no exceptions. For the five `bkit ledgers append` kinds, this column is `KIND_WRITERS` in `.bkit/core/engine/ledgers/telemetry.ts`, the check that `append` runs. `telemetry.test.ts` fails when either side changes alone.
|
|
103
|
+
|
|
104
|
+
**Stats readers keep `utility` rows apart:** `bkit stats` and the harvest report read `outcome`, `counter` and `compliance` rows in two groups: rows a workflow wrote, and rows a direct chat wrote (`by.workflow` `utility`). Each figure (run counts, durations, change size vs failures, attempt-counter trust, compliance rates, build challenge size, agent context peaks) is computed once per group, and no figure adds the two together, because no workflow run stands behind a `utility` row. The harvest's run check reads workflow `outcome` rows only, since a `utility` row has no run log.
|
|
47
105
|
|
|
48
106
|
## Generic Fields (all kinds)
|
|
49
107
|
|
|
108
|
+
Every row opens with the same top section, in this order:
|
|
109
|
+
|
|
50
110
|
<!-- prettier-ignore -->
|
|
51
111
|
| Field | Type | Meaning |
|
|
52
112
|
| --- | --- | --- |
|
|
53
|
-
| `
|
|
54
|
-
| `
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
113
|
+
| `schema` | `3` | Row format. `2` = older `plan` block (§ Shared Blocks); row without it = older shape, read through `normalize()` (§ Versioning). |
|
|
114
|
+
| `ts` | `number` | Unix milliseconds — primary id. Minted at append, never a literal (§ Write Idiom). |
|
|
115
|
+
| `firstTs` | `number?` | `deferral` / `failure` / `knowledge` / `decision` / `feature` only: `ts` of the entry's first row, never later than `ts`. Filled by the writer and by compaction (§ Compaction). |
|
|
116
|
+
| `updates` | `number?` | Same kinds: rows the entry has had, this one included (integer >= 1). Same-`ts` rows count once. |
|
|
117
|
+
| `kind` | `string` | Closed enum: `compliance`, `outcome`, `counter`, `friction`, `deferral`, `failure`, `knowledge`, `decision`, `feature`, `chat`, `run`. |
|
|
118
|
+
| `key` | `string?` | Keyed kinds only (`friction` / `deferral` / `failure` / `knowledge` / `decision` / `feature` / `chat` / `run`). See § Key & References. |
|
|
119
|
+
| `repo` | `string` | Origin repo slug, e.g. `cbartens/bkit`; its fingerprint on `chat` / `run` rows (§ Per-Kind Fields). |
|
|
120
|
+
| `bkit` | `{version}` | `version` = bkit version that emitted the row (`null` on `chat` / `run` when none found). `chat` adds its bkit-use fields. |
|
|
121
|
+
| `by` | `{workflow?, step, subagent?, model?}` | Who wrote it — § Who Wrote It. `workflow`: `design` / `plan` / `build` / `debug` / `ship` / `auto` / `audit`; `utility` for a direct chat outside any workflow; `chat-stats` on `chat` (the harvest script's scan); the run's workflow on `run`. |
|
|
61
122
|
| `references` | `string[]?` | Pointers that place the row: feature ids, tracker ids, PRs, commit SHAs, paths, a sibling `ts`. See § Key & References. |
|
|
62
123
|
|
|
124
|
+
Values in every kind:
|
|
125
|
+
|
|
126
|
+
- **Absent vs `null`:** Absent = the field does not apply. `null` = it applies but could not be measured.
|
|
127
|
+
- **Units:** Durations are in minutes, with the unit in the name (`totalMinutes`, `activeMinutes`). Timestamps are unix ms.
|
|
128
|
+
- **Totals beside parts:** Fixed parts (`code` / `tests` / `docs`) have a `total` next to them. Open-ended parts have a `total` next to a `by<What>` map (`byStep`, `byModel`, `byAgent`, `byTool`, `byCategory`, `byVerb`). The writer computes every total from its parts just before the write. `validate()` refuses a row whose total does not match, with minute totals allowed within 0.1 per part.
|
|
129
|
+
- **Run join key:** `run.parentSha` = HEAD at the run's close. It is also on the run's `workflow-done` status row. Every `compliance` / `counter` / `outcome` row of one run carries it, and `chat` carries `run.parentShas`.
|
|
130
|
+
|
|
131
|
+
## Shared Blocks
|
|
132
|
+
|
|
133
|
+
These blocks have the same name and the same shape on `outcome` and `run`:
|
|
134
|
+
|
|
135
|
+
<!-- prettier-ignore -->
|
|
136
|
+
| Block | Shape |
|
|
137
|
+
| --- | --- |
|
|
138
|
+
| `time` | `{start, end, totalMinutes}` (`end` - `start`); `chat` / `run` add `activeMinutes`, `lastActivity`. |
|
|
139
|
+
| `lines` | `{total:{added,deleted,changed,files}, code, tests, docs, merges}`; each part `{added,deleted,files}`; `changed` = `added` + `deleted`. git `--numstat` from the run's first to last commit, first-parent, cut at merges (dev syncs out); `docs/plans/**`, `docs/*.jsonl`, `.bkit/*.jsonl` out. `null` = git lacks the commits or the first is not an ancestor of the last. |
|
|
140
|
+
| `steps` | `{total:{n,totalMinutes,activeMinutes?}, byStep:{<step>:{n,totalMinutes,activeMinutes?}}}`; minutes since the previous status row, `session` / `owner-pause` / `owner-answer` rows skipped (they mark a chat or an owner wait, not a step); time before the first step only in `time.totalMinutes`. `activeMinutes` on `run` only. |
|
|
141
|
+
| `ci` | `[{status,reason,attempts}]`, one per close-step CI dispatch (`status` e.g. `dispatched` / `unresolved`). |
|
|
142
|
+
| `plan` | `{source:"file"\|"converted", total:{tasks,kb}, groups:[{tasks:[{tests,testFiles}]}]}`. `converted` = the build rewrote its input into `{FID}-plan.md` (a `build-plan-convert` status row). `total.tasks` = the sum over `groups`; `tests` / `testFiles` `null` = task has no `TEST FIRST`. `schema: 2` rows hold `source:"file"\|"brief"` (`brief` = no plan file, carries only `source`), `subPlans:[{kb, tasks}]` in place of `groups` and `complexity:{verdict,tasksChecked,reasons?}` — read as stored; the `workflowTelemetry` baseline counts `brief` as `converted`. |
|
|
143
|
+
| `build` | `{verify:[{group,attempt,verdict,failures}], gapsRemediate:[{group,attempt,verdict,strategy}], holistic:{verdict,failures}\|null, challenge:{verdict, findings:{total,CRITICAL,HIGH,MEDIUM,LOW}\|null, gate?:{size,linesChanged,filesChanged,skipped}}\|null, redTests}`; `gate` = the run's latest `challenge-gate` status row (`bkit challenge gate`; `skipped` = challenge-1 left out on a small change), absent when the run has none; `findings` = plan tasks `bkit challenge merge` appended (by `**Severity:**`) plus its `LOW` deferral rows this run (`by.step` `build-challenge`); `redTests` = `build-tests-red` step rows. |
|
|
144
|
+
|
|
63
145
|
## Per-Kind Fields
|
|
64
146
|
|
|
65
147
|
<!-- prettier-ignore -->
|
|
66
|
-
| Kind | Fields (beyond
|
|
148
|
+
| Kind | Fields (beyond the top section) |
|
|
67
149
|
| --- | --- |
|
|
68
|
-
| `counter` | `
|
|
69
|
-
| `outcome` | `parentSha
|
|
70
|
-
| `compliance` | `
|
|
150
|
+
| `counter` | `run:{parentSha}`, `counter:{name, value:number, source:"model-self-report"\|"shell-bus"}`. |
|
|
151
|
+
| `outcome` | `run:{parentSha, pr?}` (`pr` ship-only), `time` (`null` = no start row), `ending:"done"\|"close-failed"\|"held"` (`close-failed` = work done, its close's CI never started; `held` = a local build that published nothing), `publish?:boolean` (a build's resolved publish value; `false` with `held`), `lines?\|null`, `steps?`, `ci?`, `ledgers:{deferrals:{repo,added?}, failures:{repo,added?}, friction:{added?}}` (`repo` = the repo's distinct folded entries at close, not lines; `added` = distinct keys this run added — rows of `by.workflow` at or after its start; absent when the start is unknown), `plan?` (plan / build / ship), `build?` (build), `context?:{host:"claude-code", byAgent:{<agent type>:{peak, runs}}}` (the run's subagents per agent type: `runs` = subagents with a model call in the run, `peak` = largest input + cache write + cache read tokens of one model call in the run; read at close from the subagent transcripts of the closing Claude chat and of every chat the run's `session` status rows name, each call counted when its own timestamp falls between the run's start and the close; absent on other hosts or with no data; `bkit stats` judges peaks against 160,000 tokens), `ship?:{coverage?:{unit?,integration?,e2e?}}` (each `{lines,branches,functions,statements}` %; a tier absent when its coverage report is not produced). The close's CI dispatch re-appends it: dispatch added to `ci`, `ending` `close-failed` when CI never started; newer row supersedes (§ Identity / Dedup). |
|
|
152
|
+
| `compliance` | `run:{parentSha}`, `rule:{id, verdict:"pass"\|"fail"\|"n/a", evidence?}` (`evidence` on fail rows). |
|
|
71
153
|
| `friction` | `key`, `category` (§ Categories), `scope:"bkit-repo"\|"consumer"\|"universal"`, `severity`, `summary?`, `description`, `remediation?`, `source?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"\|string?` (see § Updating a Row), `confidence?:number`, `lastConfirmed?:number`, `recurrenceCount?:number`. |
|
|
72
154
|
| `deferral` | `key`, `type:"issue"\|"feature"`, `category` (§ Categories), `severity`, `reason` (§ Deferral Reason), `summary?`, `description`, `remediation?`, `source?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"?`. |
|
|
73
|
-
| `failure` | `key`, `category?` (§ Categories; `"testing"` = flaky/intermittent test), `summary?`, `severity`, `description`, `rootCause?`, `remediation?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"\|string?`. |
|
|
155
|
+
| `failure` | `key`, `category?` (§ Categories; `"testing"` = flaky / intermittent test), `summary?`, `severity`, `description`, `rootCause?`, `remediation?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"\|string?`. |
|
|
74
156
|
| `knowledge` | `key`, `summary`, `description?`, `rootCause?`, `remediation?`, `status:"ACTIVE"\|"SUPERSEDED"?`. |
|
|
75
157
|
| `decision` | `key`, `summary`, `description?`, `rationale?`, `alternatives?`, `status:"ACTIVE"\|"SUPERSEDED"?`. |
|
|
158
|
+
| `chat` | `key` (`<platform>:<session id>`); `bkit` adds `versionSource:"repo-history"\|"prompt"\|"none"` (`prompt` = an expanded workflow command's managed marker), `via` (`command` / `subagent`; empty = no bkit; `command` only when the chat ran a `/bkit-*` command itself), `workflows`, `prompts` (bkit prompt families, audit and utility included), `cli:{total, byVerb}`; `session:{platform, id, hostVersion?, entrypoint?, prompts}` (`platform` `claude-code` / `codex` / `opencode` / `cursor` / `antigravity`; `prompts` = messages the human typed); `time:{start, end, totalMinutes, activeMinutes, spans, lastActivity}` (`ts` = `end`; `spans` = `[[startMs,endMs]]`, chat + subagents, split at gaps over 5 min; `activeMinutes` = their sum; `lastActivity` = last write to the chat's files); `issue:{id, all, mentioned, source:"command"\|"summary"\|"mention"\|"none"}` (fingerprints; named only in the host's summary of an earlier chat → `summary`); `run:{parentShas}` (printed by `bkit workflows close` — exact join to `run.parentSha`); `effort` (turns per level); `usage:{total:{turns, tokens, context:{start,peak}, compactions}, main:{turns, tokens, context:{peak}, compactions, mix}, byModel:{<model>:{turns, tokens}}, byRun:{<run key>:{main:{turns, tokens}, agents:{turns, tokens}}}\|null}` (`tokens` = `{input, cacheWrite, cacheRead, output, outputEst, read}`, `read` = the three sent types; `mix` = calls by kind `{read, edit, grep, shellRead, shellList, tests, serena}`; `byRun` = the chat's model calls per run it worked on — a run's `session` rows name the chat, or same repo, the run's issue in `issue.all` and overlapping time — each call to the run whose first-to-last status row window holds its time, the later-started run when two do; `{}` = no run, `null` = a call has no time, e.g. Antigravity, Cursor); `agents:{total:{n, errors}, byAgent:{<agent type>:{n, errors, instances:[{turns, contextPeak, contextAt10}], usage, mix, planReads:{full, partial}}}}` (`contextAt10` = context read by the instance's 10th model call, `null` under 10; `planReads` = reads of a `docs/plans/<YYYYMM>/<FID>-plan(-N).md` file, `partial` = a line range or `sed` / `head` / `tail`); `tools:{total:{calls, errors}, byTool:{<tool>:{calls, errors, byCategory?}}, filesRead}`; `scan:{files, bytes, settled, tokensRecorded}` (`settled` = unchanged for the settle window, `false` = open: counted and marked, not in medians; `tokensRecorded` false = host records none, e.g. Cursor). New same-`key` row when `scan.bytes` or `scan.settled` changes, or the stored row has no `usage.byRun`. `schema: 2` chat rows hold `ctx` / `ctxPeak`; readers rename them to `context` / `contextPeak`. `repo` and issues are fingerprints: `fp:` + 12 hex of sha256(`owner/repo` / `owner/repo#N`); no paths, branch names or prompt text. Field reference: the script's header. |
|
|
159
|
+
| `run` | `key` (`<fid>:<workflow>:<start>`); `run:{fid, issue, n, parentSha, parentShas}` (`fid` = fingerprint of `owner/repo:<FID>`; `issue` = fingerprint of the FID's leading number, else `null`; `n` = nth run of that workflow in the log; `parentSha` = its last `workflow-done` row's, else its last close step's, else `null` — exact join to the run's `outcome` / `counter` / `compliance`; `parentShas` = every commit its status rows name); `time:{start, end, totalMinutes, activeMinutes, activeFrom:{chats,bytes}, lastActivity}` (first / last status row; `activeMinutes` = run time inside the spans of counted chats naming its issue by command or summary, `null` = none yet; `lastActivity` = log's last row, after-end rows included); `ending:"done"\|"close-failed"\|"failed"\|"decision-pause"\|"stopped"\|"held"` (last end row; `held` = the last `workflow-done` row says `ending: held`; `close-failed` = after `workflow-done` only the close failed: last close's CI dispatch `unresolved`, or a `workflow-failed` row with no close after it; no end row → `decision-pause` if its `build-decision-*.md` is `Status: OPEN`, else `stopped`); `ci`, `steps` (with `activeMinutes`), `lines` (build, debug), `plan` (a feature's last plan run), `build` (build) — § Shared Blocks; `owner:{waitBeforeMinutes, total:{stops, minutes}, stops:[{minutes, open, reason}]}` (owner waits from `owner-pause` → next `owner-answer` status rows, pauses before an answer joined into one stop; `open` = no answer yet, `minutes: null`; `reason` `decision` / `grill` / `draft`; `waitBeforeMinutes` = the same log's previous run's last row to this run's first, `null` for the first); `usage:{total, main, agents}\|null` (each `{turns, tokens}`; sum of the matched chats' `usage.byRun[key]`; `null` = no chat matched, or one has no `byRun`); `scan:{rows, afterEnd, settled}` (`afterEnd` = rows after the end row, e.g. a hand rewind, or the `engine-call` / `completeness` rows the engine journals after a terminator, which add to `afterEnd` and `scan.rows` with no rewind; `settled` = last row older than the settle window). `ts` = scan time. New same-`key` row when `scan.rows`, `time.activeFrom`, `scan.settled`, `usage` or `owner` changes. No limits applied; no FID text, paths or branch names. |
|
|
76
160
|
| `feature` | `key` (the FID), `category` (§ Categories), `summary?`, `description`, `status:"DESIGNED"\|"PLANNED"\|"BUILT"\|"DEBUGGED"\|"SHIPPED"\|"ABANDONED"` (required — no severity; see `docs/roadmap.md`), `shippedAt:number?` (§ Ship Date). |
|
|
77
161
|
|
|
78
|
-
## Who Wrote It — `step` vs `subagent` vs `model`
|
|
162
|
+
## Who Wrote It — `by.step` vs `by.subagent` vs `by.model`
|
|
79
163
|
|
|
80
164
|
<!-- prettier-ignore -->
|
|
81
|
-
| Row written by | `workflow` | `step` | `subagent` | `model` |
|
|
165
|
+
| Row written by | `by.workflow` | `by.step` | `by.subagent` | `by.model` |
|
|
82
166
|
| --- | --- | --- | --- | --- |
|
|
83
|
-
| **The orchestrator** (a workflow itself) | `ship` | `ship-close-
|
|
84
|
-
| **A subagent** it invoked | `build` | the step that invoked it, e.g. `build-
|
|
167
|
+
| **The orchestrator** (a workflow itself) | `ship` | `ship-close-workflow` | (absent) | (absent) |
|
|
168
|
+
| **A subagent** it invoked | `build` | the step that invoked it, e.g. `build-plan-gaps-remediate` | `bkit-build-plan-gaps-remediate` | that prompt's own `model:` |
|
|
169
|
+
| **A direct chat** outside any workflow | `utility` | `manual` | (absent) | (absent) |
|
|
85
170
|
|
|
86
|
-
Subagent: on every
|
|
171
|
+
Subagent: set these on every row you append, from your prompt file:
|
|
87
172
|
|
|
88
|
-
- **`subagent`** = your frontmatter `name:`.
|
|
89
|
-
- **`model`** = your frontmatter `model:`.
|
|
90
|
-
- **`step`** = invoking workflow step
|
|
173
|
+
- **`by.subagent`** = your frontmatter `name:`.
|
|
174
|
+
- **`by.model`** = your frontmatter `model:`.
|
|
175
|
+
- **`by.step`** = the invoking workflow step, named in your Context. Never an agent name.
|
|
176
|
+
- **`by.workflow`** = the invoking workflow.
|
|
91
177
|
|
|
92
|
-
Orchestrator: omit `subagent` and `model`.
|
|
178
|
+
Orchestrator: omit `by.subagent` and `by.model`.
|
|
93
179
|
|
|
94
180
|
## Key & References
|
|
95
181
|
|
|
96
|
-
`key` =
|
|
182
|
+
`key` = a stable slug, written once. A recurrence is a same-`key` append.
|
|
97
183
|
|
|
98
|
-
- **Mint it from the
|
|
99
|
-
- **Cite the `key`.**
|
|
184
|
+
- **Mint it from the content, never from a counter.** Use a descriptive slug (`gh-mcp-401-after-token-rotation`), optionally prefixed with the issue (`681-e2e-parallelism-via-runner-matrix`). Counter-derived ids collide under concurrency: two workflows read the same maximum off their base commit, mint the same id, and collide silently.
|
|
185
|
+
- **Cite the `key`.** It is the identity for other rows, docs and memory, and `ts` is the tiebreaker. Content slugs avoid counter collisions.
|
|
100
186
|
|
|
101
|
-
`references` = pointers
|
|
187
|
+
`references` = the pointers that place this row:
|
|
102
188
|
|
|
103
189
|
<!-- prettier-ignore -->
|
|
104
190
|
```jsonl
|
|
105
|
-
"references": ["681", "ISSUE-217", "PR-412", "a1b2c3d", "docs/plans/202607/681-e2e-parallelism-design.md", "
|
|
191
|
+
"references": ["681", "ISSUE-217", "PR-412", "a1b2c3d", "docs/plans/202607/681-e2e-parallelism-design.md", "gh-mcp-401-after-token-rotation"]
|
|
106
192
|
```
|
|
107
193
|
|
|
108
|
-
-
|
|
109
|
-
- Keep
|
|
110
|
-
-
|
|
111
|
-
- Omit when nothing to point at.
|
|
194
|
+
- A pointer is a feature id / `{FID}`, a tracker id (`ISSUE-217`), a PR, a commit SHA, a file path, or a row's `key` in the same or another ledger.
|
|
195
|
+
- Keep each item as the source wrote it. A trailing qualifier (`ISSUE-142 §A2`) is meaning, not noise.
|
|
196
|
+
- There is no separate identity field: `key` is the identity, and `references` holds pointers only.
|
|
197
|
+
- Omit the field when there is nothing to point at.
|
|
198
|
+
- Pointers between ledgers never need rewriting: a correction is a same-`key` append. When a correction affects rows in other ledgers that point at it, the ledger updater (`@bkit-utility-update-decisions`, `-knowledge`, `-deferrals`, `-failures`) reports those rows under `Cross-Ledger Impact`. Each row's own ledger writer appends any change.
|
|
112
199
|
|
|
113
|
-
## Friction Is a Drained Queue — the
|
|
200
|
+
## Friction Is a Drained Queue — the non-append-only rows
|
|
114
201
|
|
|
115
|
-
`.bkit/friction.jsonl`
|
|
202
|
+
`.bkit/friction.jsonl` is a drained work queue. The `chat` / `run` rows in `.bkit/stats.jsonl` are drained too, because they belong in `harvest/`. No other row is ever removed, apart from the superseded keyed-ledger rows that `bkit ledgers compact` drops (§ Compaction):
|
|
116
203
|
|
|
117
204
|
<!-- prettier-ignore -->
|
|
118
205
|
| Actor | May do |
|
|
119
206
|
| --- | --- |
|
|
120
207
|
| **A consumer repo** | append only. |
|
|
121
|
-
|
|
|
208
|
+
| **bkit's harvest** (`pnpm harvest`, bkit repo only, unshipped) | moves rows out: copies each into bkit's `harvest/` store, then prunes it from the repo. |
|
|
122
209
|
|
|
123
|
-
|
|
210
|
+
A row that vanishes from `.bkit/friction.jsonl` was banked centrally by the harvest.
|
|
124
211
|
|
|
125
|
-
|
|
212
|
+
The prune gates, in order:
|
|
126
213
|
|
|
127
|
-
- **Durability first
|
|
128
|
-
- **Content, never identity
|
|
129
|
-
- **Malformed lines
|
|
130
|
-
- **Store accumulates
|
|
214
|
+
- **Durability first:** Prune a row only after the exact row is fsync'd to the store and read back.
|
|
215
|
+
- **Content, never identity:** Gate byte-for-byte on the row's `normalize()` shape. An old-shape row matches its migrated copy. `fold` collapses same-identity rows, so an identity gate deletes rows the store does not hold.
|
|
216
|
+
- **Malformed lines:** Never pruned.
|
|
217
|
+
- **Store accumulates:** The store keeps every distinct row, deduped by content only. It is never cleared, and never rewritten from `fold`, because the winners shift between runs. Readers fold it. `harvest` never commits, in either repo.
|
|
131
218
|
|
|
132
|
-
`stats.jsonl`
|
|
219
|
+
`stats.jsonl` is copied whole, and only its `chat` / `run` rows are pruned. `deferrals` / `failures` are count-only, from their top-section metadata. Their prose never leaves the repo.
|
|
133
220
|
|
|
134
221
|
## Summary vs Description
|
|
135
222
|
|
|
136
|
-
|
|
223
|
+
On the kinds with both (`friction` / `deferral` / `failure` / `knowledge` / `decision` / `feature`), `summary` = a short title and `description` = the prose. When the text is one sentence, write `description` only.
|
|
137
224
|
|
|
138
225
|
## Severity
|
|
139
226
|
|
|
140
|
-
`severity` is required on `friction` / `deferral` / `failure`, and must not appear on any other kind
|
|
227
|
+
`severity` is required on `friction` / `deferral` / `failure`, and must not appear on any other kind. `knowledge` / `decision` / `feature` have no triage severity: `feature` tracks its phase through `status`, not how badly something is broken. `compliance` / `outcome` / `counter` are machine-generated by `bkit workflows close`, or written by a direct chat (`by.workflow` `utility`). `severity` is a closed enum of exactly these four values, in uppercase:
|
|
141
228
|
|
|
142
229
|
<!-- prettier-ignore -->
|
|
143
230
|
| Value | Means |
|
|
@@ -147,48 +234,50 @@ Kinds with both (`friction` / `deferral` / `failure` / `knowledge` / `decision`
|
|
|
147
234
|
| `MEDIUM` | Degraded behaviour or a repeated cost; safe to schedule. |
|
|
148
235
|
| `LOW` | Cosmetic, nit, or a speculative future idea. |
|
|
149
236
|
|
|
150
|
-
-
|
|
151
|
-
- not `bkit install` preflight `blocker` / `advisory
|
|
152
|
-
- Pick level the
|
|
237
|
+
- It is the same enum the challenge prompts assign. When a finding becomes a row (e.g. `bkit challenge merge` `LOW` → `docs/deferrals.jsonl`), carry its severity unchanged.
|
|
238
|
+
- It is not the `bkit install` preflight's `blocker` / `advisory`, which measure a different axis.
|
|
239
|
+
- Pick the level the row earns. A ledger where every row is `LOW` is as useless as one with no severity.
|
|
153
240
|
|
|
154
241
|
## Deferral Reason
|
|
155
242
|
|
|
156
|
-
`reason` required on `deferral`, absent
|
|
243
|
+
`reason` is required on `deferral`, and absent on every other kind. It says why the work is deferred, which is distinct from `status` (how far) and `severity` (how much). It is a closed enum, in lowercase:
|
|
157
244
|
|
|
158
245
|
<!-- prettier-ignore -->
|
|
159
246
|
| Value | Means | Also required |
|
|
160
247
|
| --- | --- | --- |
|
|
161
|
-
| `scope-declared` | design/plan called it out of scope before work started. | `references` to that doc §. |
|
|
248
|
+
| `scope-declared` | design / plan called it out of scope before work started. | `references` to that doc §. |
|
|
162
249
|
| `hard-blocked` | external blocker (credential, upstream fix, feature) blocks it now. | Name blocker in `description`. |
|
|
163
250
|
| `needs-decision` | human decision missing; guessing worse than waiting. | State decision + options. |
|
|
164
251
|
| `own-cycle` | plan-sized — new architecture, not a mechanical fix. | Say what makes it plan-sized. |
|
|
165
|
-
| `
|
|
252
|
+
| `low-severity` | `LOW` challenge finding, written by `bkit challenge merge`. | Name the finding. |
|
|
253
|
+
| `unjustified` | adjudicator-only — in-scope work that should have been finished. | Which test it failed. |
|
|
166
254
|
|
|
167
|
-
-
|
|
168
|
-
-
|
|
169
|
-
-
|
|
170
|
-
-
|
|
255
|
+
- **If** one of the first four fits, or `low-severity` where it applies → it is a deferral.
|
|
256
|
+
- **Else** → it is unfinished work, so do it (`.agents/rules.md` § "Finish over deferrals").
|
|
257
|
+
- `unjustified` is never self-assigned. The writer picks from the first four. A reviewer adjudicating another agent's deferral sets it through a same-`key` append.
|
|
258
|
+
- It is set once and carried verbatim by every later row, because the rate it feeds counts the deferral that should not have been written.
|
|
259
|
+
- It is never free prose. A reason nobody can adjudicate reads as a justification while being none, and the closed enum prevents that.
|
|
171
260
|
|
|
172
|
-
**The four tests.**
|
|
261
|
+
**The four tests.** A reviewer marks a row `unjustified` when all four hold. The tests never apply to a `low-severity` row:
|
|
173
262
|
|
|
174
|
-
1. `remediation` names specific files
|
|
175
|
-
2.
|
|
176
|
-
3.
|
|
177
|
-
4. `scope-declared` with no pre-existing declaration
|
|
263
|
+
1. `remediation` names specific files and a bounded edit, not a new architecture.
|
|
264
|
+
2. The surface is inside files the cycle already touched.
|
|
265
|
+
3. There is no external blocker: no missing decision, credential, upstream fix or confirmation.
|
|
266
|
+
4. The row is `scope-declared` with no pre-existing declaration: the row is the only place the work was called out of scope.
|
|
178
267
|
|
|
179
|
-
Test 4 carries the weight
|
|
268
|
+
Test 4 carries the weight. A genuine deferral was declared out of scope before the work started. An unjustified one was declared at the moment of avoidance. The ledger holds both timestamps.
|
|
180
269
|
|
|
181
270
|
## Ship Date
|
|
182
271
|
|
|
183
|
-
`shippedAt`
|
|
272
|
+
`shippedAt` is optional on `feature`, and absent on every other kind. It is the Unix ms when the feature shipped. `docs/roadmap.md` § Shipped ranks on `shippedAt // ts`.
|
|
184
273
|
|
|
185
|
-
- Set only on `status:"SHIPPED"` rows, and only when the ship predates the append
|
|
186
|
-
- may be a literal
|
|
187
|
-
-
|
|
274
|
+
- Set it only on `status:"SHIPPED"` rows, and only when the ship predates the append, as in a backfill. At a live phase close, omit it, because `ts` already is the ship time.
|
|
275
|
+
- It may be a literal, unlike `ts` (§ Write Idiom), because it is not row identity. Source it from the issue's `closed_at` or the merge-commit date.
|
|
276
|
+
- Never guess it. **If** there is no defensible source → omit it, and accept the `ts` ordering.
|
|
188
277
|
|
|
189
278
|
## Categories
|
|
190
279
|
|
|
191
|
-
|
|
280
|
+
Categories are free-form. Use the closest term, or `other` if none fits. `deferral` and `failure` use the domain set, and `friction` uses the friction set. Do not mix them.
|
|
192
281
|
|
|
193
282
|
**Domain — `deferral` + `failure`:**
|
|
194
283
|
|
|
@@ -206,147 +295,209 @@ Free-form; closest term, `other` if none. `deferral` + `failure` → domain set;
|
|
|
206
295
|
| `docs` | documentation |
|
|
207
296
|
| `other` | none of the above |
|
|
208
297
|
|
|
209
|
-
**Flaky / intermittent tests** = `failure` with `category:"testing"
|
|
298
|
+
**Flaky / intermittent tests** = `failure` rows with `category:"testing"`. Their `key` = the spec path + the test title, minted once. Each re-observation is a same-`key` append (§ Updating a Row), so the flake count = the winner's `updates`. `firstTs` / `ts` = first seen / last seen. Do not add a pass-rate or counter field.
|
|
210
299
|
|
|
211
300
|
**Friction — `friction`:**
|
|
212
301
|
|
|
213
302
|
<!-- prettier-ignore -->
|
|
214
303
|
| Term | Covers |
|
|
215
304
|
| --- | --- |
|
|
216
|
-
| `human-confirm` | human confirmation prompt |
|
|
305
|
+
| `human-confirm` | human confirmation prompt; the engine writes it when `status row --type=owner-pause` records a workflow stopping to ask the owner, so the agent does not log one. `key` = `owner-pause/<workflow>.<reason>` (`owner-pause/<workflow>` with no `reason`), kept under 60 chars like `tool-failure`; `severity` `LOW`. A follow-up wait writes no row: the status file already holds an `owner-pause` row with the same workflow and `reason` and no `step-done` row after it. A later pause at the same point appends a recurrence, as for `tool-failure`. A failed write keeps the status row and exits 4 |
|
|
217
306
|
| `permission-prompt` | tool / permission approval prompt |
|
|
218
307
|
| `agent-rework` | agent redo / self-correction |
|
|
219
308
|
| `manual-install` | manual dependency / tool install |
|
|
220
|
-
| `tool-failure` | tool / command error |
|
|
309
|
+
| `tool-failure` | tool / command error; the engine writes it on a bkit command's exit that is neither a shared routing code nor one of the verb's own `exitCodes`, or on a non-`CommandError` throw. `key` = `<noun>-<verb>/<step>` (`<step>` = the command's `--step=`, else `<noun>-<verb>`), kept under 60 chars because the identity-gated prune truncates a friction key at about 68. The first row carries `recurrenceCount` 1; a recurrence appends the same-`key` winner again with a later `ts`, `recurrenceCount` raised by one and `lastConfirmed` = that `ts` (§ Updating a Row). A `CLOSED` winner comes back `OPEN`, so a fixed failure that returns reaches triage again; a `TRIAGED` one stays `TRIAGED` |
|
|
221
310
|
| `destructive-backout` | reverted a destructive action |
|
|
222
311
|
| `other` | none of the above |
|
|
223
312
|
|
|
224
313
|
## Updating a Row
|
|
225
314
|
|
|
226
|
-
Fields that change after first write:
|
|
315
|
+
Fields that change after the first write:
|
|
227
316
|
|
|
228
317
|
<!-- prettier-ignore -->
|
|
229
318
|
| Field | Changes when |
|
|
230
319
|
| --- | --- |
|
|
231
|
-
| `status` | work closes (`OPEN`
|
|
232
|
-
| `reason` |
|
|
320
|
+
| `status` | work closes (`OPEN` → `CLOSED`), or a decision or knowledge row is `SUPERSEDED`. |
|
|
321
|
+
| `reason` | `deferral` only: a reviewer adjudicates → `unjustified`, naming the failed test in `description` and setting `status` → `TRIAGED`. One-way: never rewritten, and carried verbatim by every later row. Fold is last-wins, so omitting it erases the verdict and its rate. Gated on the live ledger. |
|
|
233
322
|
| `remediation` | the fix is known — usually after the row was logged mid-workflow. |
|
|
234
323
|
| `severity` | re-triage says it was worse or milder than first thought. |
|
|
235
|
-
| `confidence` |
|
|
236
|
-
| `lastConfirmed` |
|
|
237
|
-
| `recurrenceCount` |
|
|
324
|
+
| `confidence` | `friction` only: the same thing recurs (raise) or is contradicted (lower). |
|
|
325
|
+
| `lastConfirmed` | `friction` only: re-observed. |
|
|
326
|
+
| `recurrenceCount` | `friction` only: it happens again. |
|
|
327
|
+
|
|
328
|
+
**Update by appending a new row with the same `key`, never by editing the old line.** `fold()` takes the last row by `ts`, and older rows are history. A recurrence is an update.
|
|
238
329
|
|
|
239
|
-
**
|
|
330
|
+
**Hard, not stylistic:** `.gitattributes` sets `merge=union` on every append-only ledger, so merges concatenate and never conflict. Union keeps both sides of a conflicting hunk. Edit a line, and the stale copy survives beside its replacement. `fold` takes the last row by `ts`, so the stale copy wins whenever its `ts` is later.
|
|
240
331
|
|
|
241
|
-
|
|
332
|
+
- NEVER edit, reorder or delete a prior line. Change a row through a same-`key` append (§ Updating a Row). The only exceptions are the `bkit install` / `bkit upgrade` schema migration (§ Versioning), `bkit ledgers compact` (§ Compaction), and bkit's harvest (`pnpm harvest`, bkit repo only), which prunes a `.bkit/friction.jsonl` row or a `chat` / `run` row of `.bkit/stats.jsonl` only after the exact row is stored in `harvest/` and read back, and never prunes a malformed line (§ Friction Is a Drained Queue).
|
|
333
|
+
- **Never hand-write `ts`, in either direction:** Mint it at write time (§ Write Idiom). A future value outranks every later correction permanently, so the row can never be superseded. A backdated value loses to the rows it actually followed, so the correction it was meant to be silently never applies.
|
|
242
334
|
|
|
243
|
-
|
|
244
|
-
- **never hand-write `ts`, in either direction** — mint at write time (§ Write Idiom). Future: outranks every later correction, permanently; row can never be superseded. Backdated: loses to rows it actually followed, so the correction it was meant to be silently never applies.
|
|
335
|
+
`.bkit/friction.jsonl` is excluded, because rows are removed from it (§ Friction Is a Drained Queue) and union would resurrect a drained row.
|
|
245
336
|
|
|
246
|
-
|
|
337
|
+
To update a row, copy the prior row, change what changed, and append it. Through `bkit ledgers append`, drop `schema` / `ts` / `bkit` (`firstTs` / `updates` are recomputed), and set `by` to the writer of the new row. Carry `key` verbatim, because a reworded `key` forks the entry. Same `key` = one entry. `fold` returns the last row, so "how long open" / "time to fix" = its `ts` - `firstTs`.
|
|
247
338
|
|
|
248
|
-
|
|
339
|
+
**Triage** = sweeping `docs/deferrals.jsonl` / `docs/failures.jsonl` for work that has moved on, and appending a same-`key` row with `status: "CLOSED"`, the current `references` (PR, commit, closing issue) and a re-triaged `severity` where earned.
|
|
249
340
|
|
|
250
|
-
|
|
341
|
+
**`TRIAGED`** = the middle state of the triaged trio (`friction` / `deferral` / `failure`, the kinds with `severity`). The ladder: `OPEN` (raised, cause unknown) → `TRIAGED` (analysed, disposition known, not fixed) → `CLOSED` (fixed, refuted, or not ours). Append it the same way as a close, with the disposition in `references`: an issue, a mapped `Fix N`, or why it is not ours.
|
|
251
342
|
|
|
252
|
-
**`TRIAGED
|
|
343
|
+
**`TRIAGED` is still open work.** Open-entry counts (the audit debt lens, the age report) test `status != "CLOSED"`. Only `CLOSED` is done.
|
|
253
344
|
|
|
254
|
-
|
|
345
|
+
The ladder is not used on `knowledge` or `decision`: both use `ACTIVE` / `SUPERSEDED`. An absent `status` = `ACTIVE`.
|
|
255
346
|
|
|
256
|
-
|
|
347
|
+
**Readers** of either ledger: Fold by `key`, with the highest `ts` winning. Read only the winning rows whose `status` is `ACTIVE` or absent, and never read any other rows.
|
|
257
348
|
|
|
258
|
-
|
|
349
|
+
Readers count entities, never lines, so `fold` first.
|
|
259
350
|
|
|
260
|
-
|
|
351
|
+
## Compaction
|
|
352
|
+
|
|
353
|
+
`bkit ledgers compact [--ledger=<knowledge|decisions|deferrals|failures|issues|all>] [--dry-run]` rewrites `docs/knowledge.jsonl`, `docs/decisions.jsonl`, `docs/deferrals.jsonl`, `docs/failures.jsonl`, `.bkit/issues.jsonl` to their fold winners:
|
|
354
|
+
|
|
355
|
+
- **Drops** each row that a same-identity row with a higher `ts` supersedes. With equal `ts`, the later line wins, as in `fold`. The winner stays on its line.
|
|
356
|
+
- **Stamps** each winner with `firstTs` (the earliest `firstTs` / `ts` across the entry) and `updates` (a stamped row counts as its `updates`, each later row adds 1, and same-`ts` rows count once). Stale values are corrected.
|
|
357
|
+
- **Keeps byte-for-byte:** malformed, non-object, blank and keyless lines; rows of other kinds; a winner already carrying the right values.
|
|
358
|
+
- **Reader-invisible:** `fold` returns the same winners, apart from `firstTs` / `updates`.
|
|
359
|
+
- **Idempotent:** A second run changes nothing. When `merge=union` brings dropped rows back, the next run drops them again, with the counts unchanged.
|
|
360
|
+
- **Writes** through a temp file and a rename, only when something changes. `--dry-run` only counts.
|
|
361
|
+
- **Runs** at the end of each ledger's updater, best-effort, on its own ledger: `@bkit-utility-update-knowledge` / `-decisions` / `-deferrals` / `-failures`, `@bkit-utility-update-roadmap` → `issues`. Never at append, and never at install / upgrade.
|
|
362
|
+
- No schema change: `firstTs` / `updates` are optional, and a row without them is a one-row entry.
|
|
261
363
|
|
|
262
364
|
## These Ledgers Are Inputs, Not a Diary
|
|
263
365
|
|
|
264
|
-
`docs/deferrals.jsonl`
|
|
366
|
+
`docs/deferrals.jsonl` and `docs/failures.jsonl` are the backlog: deferred scope and known bugs. `severity` ranks them, and `firstTs` ages them (`ts` when absent). Read them:
|
|
265
367
|
|
|
266
|
-
- **Before designing or planning
|
|
267
|
-
- **On a triage sweep
|
|
268
|
-
- **When a bug looks familiar
|
|
368
|
+
- **Before designing or planning:** Grep for an existing entry or a past deferral reason.
|
|
369
|
+
- **On a triage sweep:** Walk the open entries against the tracker and the codebase. For each one, close it, mark it `TRIAGED` or re-set its `severity`, through an append (§ Updating a Row).
|
|
370
|
+
- **When a bug looks familiar:** A same-`key` `failure` is a recurrence.
|
|
269
371
|
|
|
270
|
-
Rank existing
|
|
372
|
+
Rank the existing entries `severity: CRITICAL` first, then by oldest `firstTs` (`ts` when absent).
|
|
271
373
|
|
|
272
374
|
## Identity / Dedup
|
|
273
375
|
|
|
274
|
-
Identity tuple, not bare `ts`:
|
|
376
|
+
Identity is a tuple, not a bare `ts`:
|
|
275
377
|
|
|
276
378
|
<!-- prettier-ignore -->
|
|
277
379
|
| Kind | Identity tuple |
|
|
278
380
|
| --- | --- |
|
|
279
|
-
| `compliance` | `(repo, workflow, parentSha, rule)` |
|
|
280
|
-
| `outcome` | `(repo, workflow, parentSha)` — `
|
|
281
|
-
| `counter` | `(repo, workflow, parentSha,
|
|
282
|
-
| `friction` \| `deferral` \| `failure` \| `knowledge` \| `decision` | `(kind, repo, key)` |
|
|
381
|
+
| `compliance` | `(repo, by.workflow, run.parentSha, rule.id)` |
|
|
382
|
+
| `outcome` | `(repo, by.workflow, run.parentSha)` — `run.pr` / `ts` fallback on rows without `run.parentSha`; newest `ts` wins, so a re-appended outcome supersedes |
|
|
383
|
+
| `counter` | `(repo, by.workflow, run.parentSha, counter.name)` |
|
|
384
|
+
| `friction` \| `deferral` \| `failure` \| `knowledge` \| `decision` \| `feature` \| `chat` \| `run` | `(kind, repo, key)` |
|
|
385
|
+
|
|
386
|
+
An identity match means the same thing, not an automatic skip:
|
|
387
|
+
|
|
388
|
+
- **Nothing changed** → skip.
|
|
389
|
+
- **Something changed** → append (§ Updating a Row).
|
|
283
390
|
|
|
284
|
-
|
|
391
|
+
## `engine-action` rows
|
|
285
392
|
|
|
286
|
-
-
|
|
287
|
-
|
|
393
|
+
This is not a ledger but a row in a run's `status.jsonl` (`.bkit/workflows.md` § `status.jsonl`). An engine action unsafe to repeat — a tracker comment, a marker commit, a CI re-trigger, a PR open — appends one once it is done, and checks for it first, so a re-run of the same block does not act twice. Actions safe to repeat (a label already set) record nothing.
|
|
394
|
+
|
|
395
|
+
<!-- prettier-ignore -->
|
|
396
|
+
| Field | Value |
|
|
397
|
+
| --- | --- |
|
|
398
|
+
| `type` | `engine-action` |
|
|
399
|
+
| `action` | what was done: `comment`, `commit`, `dispatch`, `pr-open`, … |
|
|
400
|
+
| `key` | the moment: workflow, run, step, sub-plan, attempt, kind, joined by `/`; an absent part is `-` (`build/2/build-plan-verify/1/3/comment`) |
|
|
401
|
+
| `hash` | sha256 hex of the body or payload acted on |
|
|
402
|
+
| `ref` | what the action made (comment URL, commit SHA, run id); `null` when it names none |
|
|
403
|
+
| `at` | UTC, whole seconds |
|
|
404
|
+
|
|
405
|
+
- **Same `key`, same `hash`** → already done: skip, print `deduped: true`.
|
|
406
|
+
- **Same `key`, new `hash`** → a deliberate edit: act again, append another row.
|
|
407
|
+
- **Helpers:** `actionKey`, `actionHash`, `alreadyDone`, `recordAction` in `.bkit/core/engine/ledgers/status.ts`. The row has no `workflow`; the fold, `runStatusRows`, `counters rows` and the status-holes audit all read by `type`, so they skip it.
|
|
288
408
|
|
|
289
409
|
## Versioning
|
|
290
410
|
|
|
291
|
-
|
|
411
|
+
`schema: 3` = the row format, and `bkit.version` = the bkit that wrote it. `schema: 2` rows differ only in the `plan` block (§ Shared Blocks). They are read as stored and never rewritten.
|
|
412
|
+
|
|
413
|
+
- **Readers normalize every row:** `normalize()` in `.bkit/core/engine/ledgers/telemetry.ts` returns a `schema` row as is. It turns a row without one into the `schema: 2` shape: `bkitVersion` → `bkit.version`, `workflow` / `step` / `subagent` / `model` → `by.*` (`null` / empty dropped), any kind's `parentSha` → `run.parentSha`, flat run fields → their blocks, `chat` total tokens summed from its models, and fields with no place dropped. `merge=union` can bring an old-shape line back from a branch, so no reader assumes a migrated file. A reader comparing rows across ledgers compares them normalized.
|
|
414
|
+
- **No version gating:** Readers ingest every well-formed row and report counts per `bkit.version`. An unexpected version surfaces for triage.
|
|
415
|
+
- **Migration:** `bkit install` / `bkit upgrade` rewrite each ledger line without `schema` through `normalize()`, in place. The rewrite is idempotent: a `schema` line, a malformed line or a non-object line stays byte-for-byte. An old line whose rewrite the file already holds is dropped (`merge=union` of a branch from before the rewrite doubles every row). This migration is a sanctioned edit of a prior line (§ Updating a Row), beside § Compaction. `bkit check` counts each ledger still holding such a line as a pending write, which is drift: exit 1 until `bkit upgrade` runs. Ledgers carry no canonical hash, so appended rows are never drift.
|
|
292
416
|
|
|
293
417
|
## Examples
|
|
294
418
|
|
|
295
|
-
|
|
419
|
+
The rows are indented here for readability. On disk, each row is a single physical line (§ Write Idiom). There is one example per ledger. Each shows the kind's fields, with the optional ones included where they apply to its workflow (§ Per-Kind Fields). The `build` block appears in the `run` example.
|
|
296
420
|
|
|
297
|
-
`.bkit/stats.jsonl` (`compliance` / `outcome` / `counter`):
|
|
421
|
+
`.bkit/stats.jsonl` (`compliance` / `outcome` / `counter`); `harvest/stats.jsonl` (`chat` / `run`):
|
|
298
422
|
|
|
299
423
|
<!-- prettier-ignore -->
|
|
300
424
|
```jsonl
|
|
301
425
|
{
|
|
426
|
+
"schema": 3,
|
|
302
427
|
"ts": 1718900000000,
|
|
303
428
|
"kind": "compliance",
|
|
304
429
|
"repo": "cbartens/bkit",
|
|
305
|
-
"
|
|
306
|
-
"workflow": "ship",
|
|
307
|
-
"
|
|
308
|
-
"rule": "
|
|
309
|
-
"result": "pass",
|
|
310
|
-
"evidence": "no mirror files present in the diff",
|
|
311
|
-
"phase": "ship",
|
|
312
|
-
"parentSha": "a1b2c3d"
|
|
430
|
+
"bkit": { "version": "5.6.0" },
|
|
431
|
+
"by": { "workflow": "ship", "step": "ship-close-workflow" },
|
|
432
|
+
"run": { "parentSha": "a1b2c3d" },
|
|
433
|
+
"rule": { "id": "skip-ci-not-head", "verdict": "fail", "evidence": "HEAD a1b2c3d carries [skip ci]" }
|
|
313
434
|
}
|
|
314
435
|
{
|
|
436
|
+
"schema": 3,
|
|
315
437
|
"ts": 1718900000100,
|
|
316
438
|
"kind": "outcome",
|
|
317
439
|
"repo": "cbartens/bkit",
|
|
318
|
-
"
|
|
319
|
-
"workflow": "ship",
|
|
320
|
-
"
|
|
321
|
-
"
|
|
322
|
-
"
|
|
323
|
-
"
|
|
324
|
-
"
|
|
325
|
-
"
|
|
326
|
-
"
|
|
327
|
-
"
|
|
328
|
-
"
|
|
329
|
-
"ciTrySuccess": 1,
|
|
330
|
-
"correctiveCommits": 0,
|
|
331
|
-
"reviewIterations": 1,
|
|
332
|
-
"deferrals": 1,
|
|
333
|
-
"failures": 0,
|
|
334
|
-
"frictionAdded": 1,
|
|
335
|
-
"deferralsAdded": 1,
|
|
336
|
-
"failuresAdded": 0,
|
|
337
|
-
"coverage": { "unit": { "lines": 87.4, "branches": 79.1, "functions": 90.2, "statements": 87.0 }, "integration": { "lines": 68.3 }, "e2e": { "lines": 41.5 } }
|
|
440
|
+
"bkit": { "version": "5.6.0" },
|
|
441
|
+
"by": { "workflow": "ship", "step": "ship-close-workflow" },
|
|
442
|
+
"run": { "parentSha": "a1b2c3d", "pr": 412 },
|
|
443
|
+
"time": { "start": 1718897600000, "end": 1718900000000, "totalMinutes": 40 },
|
|
444
|
+
"ending": "done",
|
|
445
|
+
"lines": { "total": { "added": 120, "deleted": 34, "changed": 154, "files": 7 }, "code": { "added": 80, "deleted": 20, "files": 4 }, "tests": { "added": 30, "deleted": 10, "files": 2 }, "docs": { "added": 10, "deleted": 4, "files": 1 }, "merges": 0 },
|
|
446
|
+
"steps": { "total": { "n": 2, "totalMinutes": 32.5 }, "byStep": { "ship-deferred-sweep": { "n": 1, "totalMinutes": 12.5 }, "ship-merge": { "n": 1, "totalMinutes": 20 } } },
|
|
447
|
+
"ci": [{ "status": "dispatched", "reason": null, "attempts": 1 }],
|
|
448
|
+
"ledgers": { "deferrals": { "repo": 14, "added": 1 }, "failures": { "repo": 9, "added": 0 }, "friction": { "added": 1 } },
|
|
449
|
+
"plan": { "source": "file", "total": { "tasks": 3, "kb": 48 }, "groups": [{ "tasks": [{ "tests": 2, "testFiles": 1 }, { "tests": 3, "testFiles": 2 }] }, { "tasks": [{ "tests": null, "testFiles": null }] }] },
|
|
450
|
+
"ship": { "coverage": { "unit": { "lines": 87.4, "branches": 79.1, "functions": 90.2, "statements": 87.0 }, "integration": { "lines": 68.3 }, "e2e": { "lines": 41.5 } } }
|
|
338
451
|
}
|
|
339
452
|
{
|
|
453
|
+
"schema": 3,
|
|
340
454
|
"ts": 1718900000200,
|
|
341
455
|
"kind": "counter",
|
|
342
456
|
"repo": "cbartens/bkit",
|
|
343
|
-
"
|
|
344
|
-
"workflow": "build",
|
|
345
|
-
"
|
|
346
|
-
"
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
"
|
|
457
|
+
"bkit": { "version": "5.6.0" },
|
|
458
|
+
"by": { "workflow": "build", "step": "build-close-workflow" },
|
|
459
|
+
"run": { "parentSha": "a1b2c3d" },
|
|
460
|
+
"counter": { "name": "BUILD_ATTEMPT", "value": 2, "source": "shell-bus" }
|
|
461
|
+
}
|
|
462
|
+
{
|
|
463
|
+
"schema": 3,
|
|
464
|
+
"ts": 1718903600000,
|
|
465
|
+
"kind": "chat",
|
|
466
|
+
"key": "claude-code:8f9f0a84-6f5a-503d-8484-d56d75424d11",
|
|
467
|
+
"repo": "fp:9f86d081884c",
|
|
468
|
+
"bkit": { "version": "5.6.0", "versionSource": "repo-history", "via": ["command", "subagent"], "workflows": ["build"], "prompts": ["build"], "cli": { "total": 10, "byVerb": { "steps finish": 6, "counters derive": 3, "workflows close": 1 } } },
|
|
469
|
+
"by": { "workflow": "chat-stats", "step": "scan" },
|
|
470
|
+
"session": { "platform": "claude-code", "id": "8f9f0a84-6f5a-503d-8484-d56d75424d11", "hostVersion": "2.1.299", "entrypoint": "sdk-cli", "prompts": 14 },
|
|
471
|
+
"time": { "start": 1718900000000, "end": 1718903600000, "totalMinutes": 60, "activeMinutes": 47.5, "spans": [[1718900000000, 1718902400000], [1718903150000, 1718903600000]], "lastActivity": 1718903600000 },
|
|
472
|
+
"issue": { "id": "fp:2c26b46b68ff", "all": ["fp:2c26b46b68ff"], "mentioned": [], "source": "command" },
|
|
473
|
+
"run": { "parentShas": ["a1b2c3d4e5f60718293a4b5c6d7e8f9012345678"] },
|
|
474
|
+
"effort": { "high": 118, "medium": 2 },
|
|
475
|
+
"usage": {
|
|
476
|
+
"total": { "turns": 120, "tokens": { "input": 900, "cacheWrite": 410000, "cacheRead": 9399100, "output": 52000, "outputEst": 48000, "read": 9810000 }, "context": { "start": 21000, "peak": 180000 }, "compactions": 1 },
|
|
477
|
+
"main": { "turns": 60, "tokens": { "input": 400, "cacheWrite": 210000, "cacheRead": 4189600, "output": 31000, "outputEst": 27000, "read": 4400000 }, "context": { "peak": 180000 }, "compactions": 1, "mix": { "read": 4, "edit": 6, "grep": 12, "shellRead": 9, "shellList": 1, "tests": 5, "serena": 0 } },
|
|
478
|
+
"byModel": { "claude-opus-5-5": { "turns": 120, "tokens": { "input": 900, "cacheWrite": 410000, "cacheRead": 9399100, "output": 52000, "outputEst": 48000, "read": 9810000 } } },
|
|
479
|
+
"byRun": { "fp:5d41402abc4b:build:1718900000000": { "main": { "turns": 60, "tokens": { "input": 400, "cacheWrite": 210000, "cacheRead": 4189600, "output": 31000, "outputEst": 27000, "read": 4400000 } }, "agents": { "turns": 60, "tokens": { "input": 500, "cacheWrite": 200000, "cacheRead": 5209500, "output": 21000, "outputEst": 21000, "read": 5410000 } } } }
|
|
480
|
+
},
|
|
481
|
+
"agents": { "total": { "n": 1, "errors": 2 }, "byAgent": { "bkit-build-plan-tasks": { "n": 1, "errors": 2, "instances": [{ "turns": 60, "contextPeak": 150000, "contextAt10": 64000 }], "usage": { "turns": 60, "tokens": { "input": 500, "cacheWrite": 200000, "cacheRead": 5209500, "output": 21000, "outputEst": 21000, "read": 5410000 }, "context": { "peak": 150000 }, "compactions": 0 }, "mix": { "read": 7, "edit": 19, "grep": 20, "shellRead": 11, "shellList": 0, "tests": 8, "serena": 0 }, "planReads": { "full": 1, "partial": 4 } } } },
|
|
482
|
+
"tools": { "total": { "calls": 100, "errors": 3 }, "byTool": { "Bash": { "calls": 80, "errors": 3, "byCategory": { "git": 30, "grep / rg": 25, "test runner": 15, "bkit cli": 10 } }, "Read": { "calls": 20, "errors": 0 } }, "filesRead": 14 },
|
|
483
|
+
"scan": { "files": 5, "bytes": 4812345, "settled": true, "tokensRecorded": true }
|
|
484
|
+
}
|
|
485
|
+
{
|
|
486
|
+
"schema": 3,
|
|
487
|
+
"ts": 1718910000000,
|
|
488
|
+
"kind": "run",
|
|
489
|
+
"key": "fp:4e07408562be:build:1718900000000",
|
|
490
|
+
"repo": "fp:9f86d081884c",
|
|
491
|
+
"bkit": { "version": "5.6.0" },
|
|
492
|
+
"by": { "workflow": "build", "step": "scan" },
|
|
493
|
+
"run": { "fid": "fp:4e07408562be", "issue": "fp:2c26b46b68ff", "n": 1, "parentSha": "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678", "parentShas": ["a1b2c3d4e5f60718293a4b5c6d7e8f9012345678"] },
|
|
494
|
+
"time": { "start": 1718900000000, "end": 1718910000000, "totalMinutes": 166.7, "activeMinutes": 98.4, "activeFrom": { "chats": 1, "bytes": 4812345 }, "lastActivity": 1718910000000 },
|
|
495
|
+
"ending": "done",
|
|
496
|
+
"ci": [{ "status": "dispatched", "reason": null, "attempts": 1 }],
|
|
497
|
+
"steps": { "total": { "n": 6, "totalMinutes": 63.7, "activeMinutes": 45.2 }, "byStep": { "build-plan-tasks": { "n": 1, "totalMinutes": 41.2, "activeMinutes": 30.1 }, "build-plan-verify": { "n": 2, "totalMinutes": 18.5, "activeMinutes": 12 }, "build-tests-red": { "n": 3, "totalMinutes": 4, "activeMinutes": 3.1 } } },
|
|
498
|
+
"lines": { "total": { "added": 1172, "deleted": 120, "changed": 1292, "files": 23 }, "code": { "added": 200, "deleted": 2, "files": 4 }, "tests": { "added": 938, "deleted": 104, "files": 14 }, "docs": { "added": 34, "deleted": 14, "files": 5 }, "merges": 1 },
|
|
499
|
+
"build": { "verify": [{ "group": 1, "attempt": 1, "verdict": "FAIL", "failures": 2 }, { "group": 1, "attempt": 2, "verdict": "PASS", "failures": 0 }], "gapsRemediate": [{ "group": 1, "attempt": 1, "verdict": "PASS", "strategy": "STANDARD" }], "holistic": null, "challenge": { "verdict": "CONCERNS", "findings": { "total": 5, "CRITICAL": 0, "HIGH": 0, "MEDIUM": 2, "LOW": 3 } }, "redTests": 3 },
|
|
500
|
+
"scan": { "rows": 31, "afterEnd": 0, "settled": true }
|
|
350
501
|
}
|
|
351
502
|
```
|
|
352
503
|
|
|
@@ -355,18 +506,18 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
355
506
|
<!-- prettier-ignore -->
|
|
356
507
|
```jsonl
|
|
357
508
|
{
|
|
509
|
+
"schema": 3,
|
|
358
510
|
"ts": 1718900000300,
|
|
359
511
|
"kind": "friction",
|
|
360
|
-
"repo": "cbartens/bkit",
|
|
361
|
-
"bkitVersion": "4.2.0",
|
|
362
|
-
"workflow": "ship",
|
|
363
|
-
"step": "ship-update-docs",
|
|
364
512
|
"key": "ship-dev-commit-blocked-by-pre-commit-hook",
|
|
513
|
+
"repo": "cbartens/bkit",
|
|
514
|
+
"bkit": { "version": "5.6.0" },
|
|
515
|
+
"by": { "workflow": "ship", "step": "ship-bookkeeping-push" },
|
|
365
516
|
"category": "tool-failure",
|
|
366
517
|
"scope": "bkit-repo",
|
|
367
518
|
"severity": "HIGH",
|
|
368
|
-
"summary": "ship
|
|
369
|
-
"description": "ship
|
|
519
|
+
"summary": "ship bookkeeping commit on dev blocked by the pre-commit hook",
|
|
520
|
+
"description": "the ship bookkeeping commit runs on dev, but the pre-commit hook refuses dev/main commits unless $PWD matches *.worktrees/*; git -C REPO_ROOT commit does not pass the guard and --no-verify is prohibited",
|
|
370
521
|
"remediation": "commit via a temp branch (docs/ship-{FID}) from dev in a temp worktree, then FF-merge dev",
|
|
371
522
|
"source": "orchestrator",
|
|
372
523
|
"status": "OPEN",
|
|
@@ -382,15 +533,13 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
382
533
|
<!-- prettier-ignore -->
|
|
383
534
|
```jsonl
|
|
384
535
|
{
|
|
536
|
+
"schema": 3,
|
|
385
537
|
"ts": 1718900000400,
|
|
386
538
|
"kind": "deferral",
|
|
387
|
-
"repo": "cbartens/bkit",
|
|
388
|
-
"bkitVersion": "4.2.0",
|
|
389
|
-
"workflow": "design",
|
|
390
|
-
"step": "design-brainstorm",
|
|
391
|
-
"subagent": "bkit-design-generate",
|
|
392
|
-
"model": "claude-opus-4-8",
|
|
393
539
|
"key": "pnpm-tag-drop-readme-note",
|
|
540
|
+
"repo": "cbartens/bkit",
|
|
541
|
+
"bkit": { "version": "5.6.0" },
|
|
542
|
+
"by": { "workflow": "design", "step": "design-generate", "subagent": "bkit-design-generate", "model": "claude-opus-5-5" },
|
|
394
543
|
"type": "issue",
|
|
395
544
|
"category": "infra",
|
|
396
545
|
"severity": "LOW",
|
|
@@ -409,23 +558,21 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
409
558
|
<!-- prettier-ignore -->
|
|
410
559
|
```jsonl
|
|
411
560
|
{
|
|
561
|
+
"schema": 3,
|
|
412
562
|
"ts": 1718900000500,
|
|
413
563
|
"kind": "failure",
|
|
564
|
+
"key": "hook-git-dir-leaks-into-temp-repo-tests",
|
|
414
565
|
"repo": "cbartens/bkit",
|
|
415
|
-
"
|
|
416
|
-
"workflow": "debug",
|
|
417
|
-
"step": "debug-diagnose",
|
|
418
|
-
"subagent": "bkit-debug-failure-diagnose",
|
|
419
|
-
"model": "claude-opus-4-8",
|
|
420
|
-
"key": "bkit-install-flips-core-bare",
|
|
566
|
+
"bkit": { "version": "5.6.0" },
|
|
567
|
+
"by": { "workflow": "debug", "step": "debug-failure-diagnose", "subagent": "bkit-debug-failure-diagnose", "model": "claude-opus-5-5" },
|
|
421
568
|
"category": "tooling",
|
|
422
|
-
"summary": "
|
|
569
|
+
"summary": "Tests run from a git hook act on the real repo",
|
|
423
570
|
"severity": "HIGH",
|
|
424
|
-
"description": "
|
|
425
|
-
"rootCause": "
|
|
426
|
-
"remediation": "
|
|
571
|
+
"description": "after a pre-push run, git config core.bare=true on the main checkout, which breaks git checkout/status",
|
|
572
|
+
"rootCause": "git exports GIT_DIR to hooks; a test running `git init --bare` with no path in its temp folder re-initialises the real repo as bare",
|
|
573
|
+
"remediation": "delete every GIT_* variable in the test setup before any test spawns git",
|
|
427
574
|
"status": "OPEN",
|
|
428
|
-
"references": ["176", "a1b2c3d", ".
|
|
575
|
+
"references": ["176", "a1b2c3d", "vitest.setup.ts"]
|
|
429
576
|
}
|
|
430
577
|
```
|
|
431
578
|
|
|
@@ -434,15 +581,13 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
434
581
|
<!-- prettier-ignore -->
|
|
435
582
|
```jsonl
|
|
436
583
|
{
|
|
584
|
+
"schema": 3,
|
|
437
585
|
"ts": 1718900000600,
|
|
438
586
|
"kind": "knowledge",
|
|
439
|
-
"repo": "cbartens/bkit",
|
|
440
|
-
"bkitVersion": "4.2.0",
|
|
441
|
-
"workflow": "debug",
|
|
442
|
-
"step": "debug-remediate",
|
|
443
|
-
"subagent": "bkit-debug-failure-remediate",
|
|
444
|
-
"model": "claude-sonnet-4-6",
|
|
445
587
|
"key": "gh-mcp-401-after-token-rotation",
|
|
588
|
+
"repo": "cbartens/bkit",
|
|
589
|
+
"bkit": { "version": "5.6.0" },
|
|
590
|
+
"by": { "workflow": "debug", "step": "debug-failure-remediate", "subagent": "bkit-debug-failure-remediate", "model": "claude-sonnet-5-5" },
|
|
446
591
|
"summary": "GitHub MCP / gh 401 immediately after a token rotation",
|
|
447
592
|
"description": "401 from the GitHub MCP server or gh despite a freshly-rotated, valid, correctly-scoped PAT in .bkit/.env",
|
|
448
593
|
"rootCause": "the MCP server captures GH_MCP_TOKEN at process launch, so a mid-session rotation leaves it holding the dead token",
|
|
@@ -457,15 +602,13 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
457
602
|
<!-- prettier-ignore -->
|
|
458
603
|
```jsonl
|
|
459
604
|
{
|
|
605
|
+
"schema": 3,
|
|
460
606
|
"ts": 1718900000700,
|
|
461
607
|
"kind": "decision",
|
|
462
|
-
"repo": "cbartens/bkit",
|
|
463
|
-
"bkitVersion": "4.2.0",
|
|
464
|
-
"workflow": "plan",
|
|
465
|
-
"step": "plan-generate",
|
|
466
|
-
"subagent": "bkit-plan-generate",
|
|
467
|
-
"model": "claude-opus-4-8",
|
|
468
608
|
"key": "bkit-distribution-via-npmjs",
|
|
609
|
+
"repo": "cbartens/bkit",
|
|
610
|
+
"bkit": { "version": "5.6.0" },
|
|
611
|
+
"by": { "workflow": "plan", "step": "plan-generate", "subagent": "bkit-plan-generate", "model": "claude-opus-5-5" },
|
|
469
612
|
"summary": "publish @cbartens/bkit publicly on npmjs",
|
|
470
613
|
"description": "publish @cbartens/bkit publicly on npmjs; consumers install with no registry mapping, PAT, or CI/Vercel env",
|
|
471
614
|
"rationale": "public install needs no registry mapping or token; release.yml publishes from CI via npm OIDC trusted publishing",
|
|
@@ -480,13 +623,13 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
480
623
|
<!-- prettier-ignore -->
|
|
481
624
|
```jsonl
|
|
482
625
|
{
|
|
626
|
+
"schema": 3,
|
|
483
627
|
"ts": 1718900000800,
|
|
484
628
|
"kind": "feature",
|
|
485
|
-
"repo": "cbartens/bkit",
|
|
486
|
-
"bkitVersion": "4.2.0",
|
|
487
|
-
"workflow": "build",
|
|
488
|
-
"step": "build-close-workflow",
|
|
489
629
|
"key": "412-export-csv",
|
|
630
|
+
"repo": "cbartens/bkit",
|
|
631
|
+
"bkit": { "version": "5.6.0" },
|
|
632
|
+
"by": { "workflow": "build", "step": "build-close-workflow" },
|
|
490
633
|
"category": "correctness",
|
|
491
634
|
"summary": "CSV export for the reporting page",
|
|
492
635
|
"description": "adds a bounded CSV export button to the reporting page, streamed server-side",
|