@cbartens/bkit 6.0.0 → 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 +154 -151
- package/.bkit/core/.agents/context.md +95 -29
- package/.bkit/core/.agents/docs.md +17 -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 +108 -107
- package/.bkit/core/.agents/skills.md +63 -15
- package/.bkit/core/.bkit/README.md +154 -151
- package/.bkit/core/.bkit/authoring.md +714 -84
- package/.bkit/core/.bkit/cli.md +407 -0
- package/.bkit/core/.bkit/cloud.md +281 -193
- package/.bkit/core/.bkit/comparison.md +43 -41
- package/.bkit/core/.bkit/install.md +154 -84
- package/.bkit/core/.bkit/jsonl.md +193 -130
- package/.bkit/core/.bkit/pipeline.md +114 -114
- package/.bkit/core/.bkit/prompts.md +272 -165
- package/.bkit/core/.bkit/providers.md +457 -271
- package/.bkit/core/.bkit/router.md +69 -0
- package/.bkit/core/.bkit/templates.md +529 -256
- package/.bkit/core/.bkit/trackers.md +80 -52
- package/.bkit/core/.bkit/workflows.md +589 -504
- 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 +5 -73
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
- package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
- package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
- package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
- package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
- package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
- package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
- package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
- package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
- package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
- package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
- package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
- package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
- package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
- package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
- package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
- package/.bkit/core/docs/templates/bkit-plan.md +138 -132
- package/.bkit/core/engine/checks/after/auth.ts +40 -37
- package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
- package/.bkit/core/engine/checks/after/index.ts +12 -2
- package/.bkit/core/engine/checks/after/tools.ts +80 -33
- package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
- package/.bkit/core/engine/checks/before/env.ts +1 -1
- package/.bkit/core/engine/checks/before/index.ts +7 -0
- package/.bkit/core/engine/checks/before/repo.ts +40 -0
- package/.bkit/core/engine/checks/status-holes.ts +916 -123
- package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
- package/.bkit/core/engine/checks/tips/detect.ts +32 -0
- package/.bkit/core/engine/checks/tips/index.ts +47 -6
- package/.bkit/core/engine/cli.ts +238 -84
- package/.bkit/core/engine/commands/analysis.ts +128 -76
- 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/install/uninstall.ts +21 -27
- package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
- package/.bkit/core/engine/commands/land.ts +126 -11
- package/.bkit/core/engine/commands/lib.ts +303 -6
- package/.bkit/core/engine/commands/registry.ts +6 -2
- package/.bkit/core/engine/commands/setup/setup.ts +1 -0
- package/.bkit/core/engine/commands/stats.ts +91 -35
- package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
- package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
- package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
- package/.bkit/core/engine/commands/workflow/context.ts +433 -55
- package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
- package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
- package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
- package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
- package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
- package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
- package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
- package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
- package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
- package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
- package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
- package/.bkit/core/engine/commands/workflow/status.ts +200 -17
- package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
- package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
- package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
- 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 +1285 -356
- package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
- package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
- 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 +60 -12
- package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
- package/.bkit/core/engine/install/modules/cloud.ts +3 -3
- package/.bkit/core/engine/install/modules/codex.ts +15 -2
- package/.bkit/core/engine/install/modules/core.ts +956 -52
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/opencode.ts +16 -4
- package/.bkit/core/engine/install/template-notes.ts +130 -0
- package/.bkit/core/engine/install/version-file.ts +3 -2
- 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/status.ts +160 -9
- package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
- package/.bkit/core/engine/render/hosts.ts +114 -14
- package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
- package/.bkit/core/engine/shared/dep-updater.ts +60 -0
- package/.bkit/core/engine/shared/egress.ts +1 -1
- package/.bkit/core/engine/shared/package-manager.ts +9 -0
- package/.bkit/core/engine/shared/settings.ts +92 -17
- 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 +1 -1
- package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
- package/.bkit/core/engine/tools/instructions.ts +94 -43
- package/.bkit/core/hooks/antigravity-hook.js +25 -10
- package/.bkit/core/hooks/gateguard-engine.js +53 -29
- package/.bkit/core/hooks/guardrails-shell.js +4 -4
- package/.bkit/core/hooks/guardrails-tiers.js +3 -3
- 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 +187 -116
- package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
- package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
- package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
- package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
- package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
- 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 +87 -50
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
- package/.bkit/core/prompts/bkit-design-generate.md +68 -52
- package/.bkit/core/prompts/bkit-design-organise.md +73 -35
- package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
- package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
- package/.bkit/core/prompts/bkit-design-spike.md +54 -47
- package/.bkit/core/prompts/bkit-design-update.md +42 -31
- package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
- package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
- package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
- package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
- package/.bkit/core/prompts/bkit-plan-update.md +70 -52
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
- package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
- package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
- package/.bkit/core/workflows/bkit-auto.md +53 -30
- package/.bkit/core/workflows/bkit-build.md +635 -304
- package/.bkit/core/workflows/bkit-debug.md +301 -148
- package/.bkit/core/workflows/bkit-design.md +167 -95
- package/.bkit/core/workflows/bkit-plan.md +172 -84
- package/.bkit/core/workflows/bkit-ship.md +299 -152
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
- package/.bkit/shared/.claude/bkit-cloud.md +12 -10
- package/.bkit/shared/.claude/settings.json +3 -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/.opencode/opencode.json +1 -1
- package/.bkit/shared/CLAUDE.md +5 -1
- package/.bkit/shared/GEMINI.md +4 -1
- package/.bkit/shared/docs/architecture.md +4 -7
- package/.bkit/shared/docs/data-schema.md +4 -7
- package/.bkit/shared/docs/deployments.md +239 -166
- 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 +282 -176
- 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 +24 -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 +53 -50
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
- 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 +95 -35
- package/.bkit/templates/.prettierignore +6 -7
- 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 +9 -1
- 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 +119 -0
- package/README.md +250 -76
- package/dist/checks/after/auth.js +36 -33
- package/dist/checks/after/ci-yml.js +52 -2
- package/dist/checks/after/index.js +12 -4
- package/dist/checks/after/tools.js +73 -33
- package/dist/checks/before/context-fetch.js +218 -33
- package/dist/checks/before/env.js +1 -1
- package/dist/checks/before/index.js +6 -2
- package/dist/checks/before/repo.js +35 -1
- package/dist/checks/status-holes.js +739 -114
- package/dist/checks/tips/catalogue.js +59 -17
- package/dist/checks/tips/detect.js +30 -0
- package/dist/checks/tips/index.js +48 -6
- package/dist/cli.js +222 -84
- package/dist/commands/analysis.js +77 -53
- 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/install/uninstall.js +23 -27
- package/dist/commands/install/upgrade.js +21 -11
- package/dist/commands/land.js +126 -10
- package/dist/commands/lib.js +244 -5
- package/dist/commands/registry.js +6 -2
- package/dist/commands/setup/setup.js +1 -0
- package/dist/commands/stats.js +69 -30
- package/dist/commands/workflow/branches.js +1232 -111
- package/dist/commands/workflow/challenge.js +90 -37
- package/dist/commands/workflow/completeness.js +97 -0
- package/dist/commands/workflow/context.js +371 -51
- package/dist/commands/workflow/counters.js +206 -40
- package/dist/commands/workflow/decisions.js +60 -17
- package/dist/commands/workflow/disk.js +213 -55
- package/dist/commands/workflow/fids.js +18 -1
- package/dist/commands/workflow/issues.js +6 -0
- package/dist/commands/workflow/ledgers.js +372 -21
- package/dist/commands/workflow/locks.js +2 -0
- package/dist/commands/workflow/plan-blocks.js +78 -14
- package/dist/commands/workflow/plans.js +205 -0
- package/dist/commands/workflow/prs.js +12 -3
- package/dist/commands/workflow/repo.js +6 -0
- package/dist/commands/workflow/roadmap.js +50 -17
- package/dist/commands/workflow/run-facts.js +23 -28
- package/dist/commands/workflow/runs.js +530 -33
- package/dist/commands/workflow/runtime.js +3 -0
- package/dist/commands/workflow/skills.js +1 -0
- package/dist/commands/workflow/status.js +166 -19
- package/dist/commands/workflow/step-table.js +61 -29
- package/dist/commands/workflow/steps.js +542 -26
- package/dist/commands/workflow/summary-findings.js +117 -0
- package/dist/commands/workflow/summary.js +154 -41
- 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 +1013 -321
- package/dist/commands/workflow/workflows.js +191 -38
- package/dist/commands/workflow/worktrees.js +310 -42
- package/dist/install/cloud-env.js +233 -99
- package/dist/install/context-ci-workflow.js +85 -0
- package/dist/install/manifest.js +57 -12
- package/dist/install/modules/antigravity.js +3 -2
- package/dist/install/modules/cloud.js +3 -3
- package/dist/install/modules/codex.js +12 -2
- package/dist/install/modules/core.js +851 -53
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/opencode.js +11 -5
- package/dist/install/template-notes.js +116 -0
- package/dist/install/version-file.js +3 -2
- package/dist/ledgers/compact.js +87 -0
- package/dist/ledgers/journal.js +233 -0
- package/dist/ledgers/status.js +115 -5
- package/dist/ledgers/telemetry.js +121 -17
- package/dist/render/hosts.js +100 -14
- package/dist/shared/bkit-latest.js +26 -4
- package/dist/shared/dep-updater.js +49 -0
- package/dist/shared/egress.js +1 -1
- package/dist/shared/package-manager.js +6 -0
- package/dist/shared/settings.js +59 -10
- package/dist/shared/timeouts.js +2 -0
- package/dist/tools/cli-doc.js +97 -0
- package/dist/tools/grammar-density.js +1 -1
- package/dist/tools/instructions-sources.js +15 -16
- package/dist/tools/instructions.js +83 -39
- package/package.json +58 -42
- package/.bkit/core/.bkit/lite.md +0 -73
- package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
- package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
- package/dist/commands/workflow/workstreams.js +0 -149
- /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,28 +3,70 @@
|
|
|
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
|
|
|
20
|
-
**Engine and workflow writers:** `bkit ledgers append --ledger=<decisions|deferrals|failures|knowledge|friction|stats> --rows=<file
|
|
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`.
|
|
21
63
|
|
|
22
|
-
- **Fills:** `schema: 3`, a minted `ts` per row, `repo` when absent, `bkit.version` from `.bkit/version`.
|
|
23
|
-
- **Checks** every row
|
|
24
|
-
- **Refused:** supplied `schema` / `ts` / `bkit`; flat `bkitVersion` / `workflow` / `step` / `subagent` / `model
|
|
25
|
-
- `--ledger=stats` takes `compliance` / `counter` / `outcome`
|
|
26
|
-
-
|
|
27
|
-
- `feature`
|
|
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.
|
|
28
70
|
|
|
29
71
|
**Humans and scripts:** the `jq` idiom:
|
|
30
72
|
|
|
@@ -33,30 +75,33 @@ jq -c -n '{ schema: 3, ts: null, kind: "deferral", repo: $REPO, bkit: { version:
|
|
|
33
75
|
>> "$FILE" || echo "[bkit-telemetry] append failed: $FILE"
|
|
34
76
|
```
|
|
35
77
|
|
|
36
|
-
- **`ts`:** Unix ms, always minted by `jq`'s `now`
|
|
37
|
-
- **`ts` is never a literal.**
|
|
38
|
-
-
|
|
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.
|
|
39
82
|
|
|
40
83
|
## Ledgers & Writers
|
|
41
84
|
|
|
42
|
-
|
|
85
|
+
Each `kind` goes to one file. Its writers:
|
|
43
86
|
|
|
44
87
|
<!-- prettier-ignore -->
|
|
45
88
|
| Kind | File | Written by |
|
|
46
89
|
| --- | --- | --- |
|
|
47
|
-
| `compliance` | `.bkit/stats.jsonl` | `bkit workflows close` of design / plan / build / debug / ship (its grader, one row per rule) |
|
|
48
|
-
| `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) |
|
|
49
|
-
| `counter` | `.bkit/stats.jsonl` | `bkit workflows close` of design / plan / build / debug / ship (attempt counters) |
|
|
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) |
|
|
50
93
|
| `chat` | `harvest/stats.jsonl` (bkit repo only) | bkit's harvest script: per agent chat on the maintainer's machine, any repo or host |
|
|
51
94
|
| `run` | `harvest/stats.jsonl` (bkit repo only) | Same script: per workflow run in the run logs of every repo a chat ran in |
|
|
52
|
-
| `friction` | `.bkit/friction.jsonl` | orchestrator workflows (design / plan / build / debug / ship) on observed friction |
|
|
53
|
-
| `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`) |
|
|
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) |
|
|
54
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) |
|
|
55
|
-
| `knowledge` | `docs/knowledge.jsonl` | `@bkit-build-plan-
|
|
56
|
-
| `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), plan orchestrator (open question answered after close), ship orchestrator (assumed accept confirmed by the owner, through `bkit decisions apply --by=owner`); orchestrators ONLY after explicit human approval |
|
|
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 |
|
|
57
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 |
|
|
58
101
|
|
|
59
|
-
**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.
|
|
60
105
|
|
|
61
106
|
## Generic Fields (all kinds)
|
|
62
107
|
|
|
@@ -67,23 +112,25 @@ Every row opens with the same top section, in this order:
|
|
|
67
112
|
| --- | --- | --- |
|
|
68
113
|
| `schema` | `3` | Row format. `2` = older `plan` block (§ Shared Blocks); row without it = older shape, read through `normalize()` (§ Versioning). |
|
|
69
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. |
|
|
70
117
|
| `kind` | `string` | Closed enum: `compliance`, `outcome`, `counter`, `friction`, `deferral`, `failure`, `knowledge`, `decision`, `feature`, `chat`, `run`. |
|
|
71
118
|
| `key` | `string?` | Keyed kinds only (`friction` / `deferral` / `failure` / `knowledge` / `decision` / `feature` / `chat` / `run`). See § Key & References. |
|
|
72
119
|
| `repo` | `string` | Origin repo slug, e.g. `cbartens/bkit`; its fingerprint on `chat` / `run` rows (§ Per-Kind Fields). |
|
|
73
120
|
| `bkit` | `{version}` | `version` = bkit version that emitted the row (`null` on `chat` / `run` when none found). `chat` adds its bkit-use fields. |
|
|
74
|
-
| `by` | `{workflow?, step, subagent?, model?}` | Who wrote it — § Who Wrote It. `workflow`: `design` / `plan` / `build` / `debug` / `ship` / `audit`; `chat-stats` on `chat` (the harvest script's scan); the run's workflow on `run`. |
|
|
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`. |
|
|
75
122
|
| `references` | `string[]?` | Pointers that place the row: feature ids, tracker ids, PRs, commit SHAs, paths, a sibling `ts`. See § Key & References. |
|
|
76
123
|
|
|
77
|
-
Values
|
|
124
|
+
Values in every kind:
|
|
78
125
|
|
|
79
|
-
- **Absent vs `null`:**
|
|
80
|
-
- **Units:**
|
|
81
|
-
- **Totals beside parts:**
|
|
82
|
-
- **Run join key:** `run.parentSha` = HEAD at the run's close
|
|
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`.
|
|
83
130
|
|
|
84
131
|
## Shared Blocks
|
|
85
132
|
|
|
86
|
-
|
|
133
|
+
These blocks have the same name and the same shape on `outcome` and `run`:
|
|
87
134
|
|
|
88
135
|
<!-- prettier-ignore -->
|
|
89
136
|
| Block | Shape |
|
|
@@ -93,7 +140,7 @@ Same name, same shape on `outcome` and `run`:
|
|
|
93
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. |
|
|
94
141
|
| `ci` | `[{status,reason,attempts}]`, one per close-step CI dispatch (`status` e.g. `dispatched` / `unresolved`). |
|
|
95
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`. |
|
|
96
|
-
| `build` | `{verify:[{group,attempt,verdict,failures
|
|
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. |
|
|
97
144
|
|
|
98
145
|
## Per-Kind Fields
|
|
99
146
|
|
|
@@ -101,15 +148,15 @@ Same name, same shape on `outcome` and `run`:
|
|
|
101
148
|
| Kind | Fields (beyond the top section) |
|
|
102
149
|
| --- | --- |
|
|
103
150
|
| `counter` | `run:{parentSha}`, `counter:{name, value:number, source:"model-self-report"\|"shell-bus"}`. |
|
|
104
|
-
| `outcome` | `run:{parentSha, pr?}` (`pr` ship-only), `time` (`null` = no start row), `ending:"done"\|"close-failed"` (`close-failed` = work done, its close's CI never started), `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
|
|
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). |
|
|
105
152
|
| `compliance` | `run:{parentSha}`, `rule:{id, verdict:"pass"\|"fail"\|"n/a", evidence?}` (`evidence` on fail rows). |
|
|
106
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`. |
|
|
107
154
|
| `deferral` | `key`, `type:"issue"\|"feature"`, `category` (§ Categories), `severity`, `reason` (§ Deferral Reason), `summary?`, `description`, `remediation?`, `source?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"?`. |
|
|
108
|
-
| `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?`. |
|
|
109
156
|
| `knowledge` | `key`, `summary`, `description?`, `rootCause?`, `remediation?`, `status:"ACTIVE"\|"SUPERSEDED"?`. |
|
|
110
157
|
| `decision` | `key`, `summary`, `description?`, `rationale?`, `alternatives?`, `status:"ACTIVE"\|"SUPERSEDED"?`. |
|
|
111
|
-
| `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.
|
|
112
|
-
| `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"` (last end row; `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
|
|
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. |
|
|
113
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). |
|
|
114
161
|
|
|
115
162
|
## Who Wrote It — `by.step` vs `by.subagent` vs `by.model`
|
|
@@ -117,65 +164,67 @@ Same name, same shape on `outcome` and `run`:
|
|
|
117
164
|
<!-- prettier-ignore -->
|
|
118
165
|
| Row written by | `by.workflow` | `by.step` | `by.subagent` | `by.model` |
|
|
119
166
|
| --- | --- | --- | --- | --- |
|
|
120
|
-
| **The orchestrator** (a workflow itself) | `ship` | `ship-close-workflow` |
|
|
167
|
+
| **The orchestrator** (a workflow itself) | `ship` | `ship-close-workflow` | (absent) | (absent) |
|
|
121
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) |
|
|
122
170
|
|
|
123
|
-
Subagent: on every
|
|
171
|
+
Subagent: set these on every row you append, from your prompt file:
|
|
124
172
|
|
|
125
173
|
- **`by.subagent`** = your frontmatter `name:`.
|
|
126
174
|
- **`by.model`** = your frontmatter `model:`.
|
|
127
|
-
- **`by.step`** = invoking workflow step
|
|
128
|
-
- **`by.workflow`** = invoking workflow.
|
|
175
|
+
- **`by.step`** = the invoking workflow step, named in your Context. Never an agent name.
|
|
176
|
+
- **`by.workflow`** = the invoking workflow.
|
|
129
177
|
|
|
130
178
|
Orchestrator: omit `by.subagent` and `by.model`.
|
|
131
179
|
|
|
132
180
|
## Key & References
|
|
133
181
|
|
|
134
|
-
`key` =
|
|
182
|
+
`key` = a stable slug, written once. A recurrence is a same-`key` append.
|
|
135
183
|
|
|
136
|
-
- **Mint it from the
|
|
137
|
-
- **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.
|
|
138
186
|
|
|
139
|
-
`references` = pointers
|
|
187
|
+
`references` = the pointers that place this row:
|
|
140
188
|
|
|
141
189
|
<!-- prettier-ignore -->
|
|
142
190
|
```jsonl
|
|
143
|
-
"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"]
|
|
144
192
|
```
|
|
145
193
|
|
|
146
|
-
-
|
|
147
|
-
- Keep
|
|
148
|
-
-
|
|
149
|
-
- 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.
|
|
150
199
|
|
|
151
200
|
## Friction Is a Drained Queue — the non-append-only rows
|
|
152
201
|
|
|
153
|
-
`.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):
|
|
154
203
|
|
|
155
204
|
<!-- prettier-ignore -->
|
|
156
205
|
| Actor | May do |
|
|
157
206
|
| --- | --- |
|
|
158
207
|
| **A consumer repo** | append only. |
|
|
159
|
-
| **bkit's harvest** (`pnpm harvest`, bkit repo only, unshipped) |
|
|
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. |
|
|
160
209
|
|
|
161
|
-
|
|
210
|
+
A row that vanishes from `.bkit/friction.jsonl` was banked centrally by the harvest.
|
|
162
211
|
|
|
163
|
-
|
|
212
|
+
The prune gates, in order:
|
|
164
213
|
|
|
165
|
-
- **Durability first
|
|
166
|
-
- **Content, never identity
|
|
167
|
-
- **Malformed lines
|
|
168
|
-
- **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.
|
|
169
218
|
|
|
170
|
-
`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.
|
|
171
220
|
|
|
172
221
|
## Summary vs Description
|
|
173
222
|
|
|
174
|
-
|
|
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.
|
|
175
224
|
|
|
176
225
|
## Severity
|
|
177
226
|
|
|
178
|
-
`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:
|
|
179
228
|
|
|
180
229
|
<!-- prettier-ignore -->
|
|
181
230
|
| Value | Means |
|
|
@@ -185,49 +234,50 @@ Kinds with both (`friction` / `deferral` / `failure` / `knowledge` / `decision`
|
|
|
185
234
|
| `MEDIUM` | Degraded behaviour or a repeated cost; safe to schedule. |
|
|
186
235
|
| `LOW` | Cosmetic, nit, or a speculative future idea. |
|
|
187
236
|
|
|
188
|
-
-
|
|
189
|
-
- not `bkit install` preflight `blocker` / `advisory
|
|
190
|
-
- 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.
|
|
191
240
|
|
|
192
241
|
## Deferral Reason
|
|
193
242
|
|
|
194
|
-
`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:
|
|
195
244
|
|
|
196
245
|
<!-- prettier-ignore -->
|
|
197
246
|
| Value | Means | Also required |
|
|
198
247
|
| --- | --- | --- |
|
|
199
|
-
| `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 §. |
|
|
200
249
|
| `hard-blocked` | external blocker (credential, upstream fix, feature) blocks it now. | Name blocker in `description`. |
|
|
201
250
|
| `needs-decision` | human decision missing; guessing worse than waiting. | State decision + options. |
|
|
202
251
|
| `own-cycle` | plan-sized — new architecture, not a mechanical fix. | Say what makes it plan-sized. |
|
|
203
252
|
| `low-severity` | `LOW` challenge finding, written by `bkit challenge merge`. | Name the finding. |
|
|
204
|
-
| `unjustified` |
|
|
253
|
+
| `unjustified` | adjudicator-only — in-scope work that should have been finished. | Which test it failed. |
|
|
205
254
|
|
|
206
|
-
-
|
|
207
|
-
-
|
|
208
|
-
-
|
|
209
|
-
-
|
|
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.
|
|
210
260
|
|
|
211
|
-
**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:
|
|
212
262
|
|
|
213
|
-
1. `remediation` names specific files
|
|
214
|
-
2.
|
|
215
|
-
3.
|
|
216
|
-
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.
|
|
217
267
|
|
|
218
|
-
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.
|
|
219
269
|
|
|
220
270
|
## Ship Date
|
|
221
271
|
|
|
222
|
-
`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`.
|
|
223
273
|
|
|
224
|
-
- Set only on `status:"SHIPPED"` rows, and only when the ship predates the append
|
|
225
|
-
- may be a literal
|
|
226
|
-
-
|
|
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.
|
|
227
277
|
|
|
228
278
|
## Categories
|
|
229
279
|
|
|
230
|
-
|
|
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.
|
|
231
281
|
|
|
232
282
|
**Domain — `deferral` + `failure`:**
|
|
233
283
|
|
|
@@ -245,72 +295,85 @@ Free-form; closest term, `other` if none. `deferral` + `failure` → domain set;
|
|
|
245
295
|
| `docs` | documentation |
|
|
246
296
|
| `other` | none of the above |
|
|
247
297
|
|
|
248
|
-
**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.
|
|
249
299
|
|
|
250
300
|
**Friction — `friction`:**
|
|
251
301
|
|
|
252
302
|
<!-- prettier-ignore -->
|
|
253
303
|
| Term | Covers |
|
|
254
304
|
| --- | --- |
|
|
255
|
-
| `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 |
|
|
256
306
|
| `permission-prompt` | tool / permission approval prompt |
|
|
257
307
|
| `agent-rework` | agent redo / self-correction |
|
|
258
308
|
| `manual-install` | manual dependency / tool install |
|
|
259
|
-
| `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` |
|
|
260
310
|
| `destructive-backout` | reverted a destructive action |
|
|
261
311
|
| `other` | none of the above |
|
|
262
312
|
|
|
263
313
|
## Updating a Row
|
|
264
314
|
|
|
265
|
-
Fields that change after first write:
|
|
315
|
+
Fields that change after the first write:
|
|
266
316
|
|
|
267
317
|
<!-- prettier-ignore -->
|
|
268
318
|
| Field | Changes when |
|
|
269
319
|
| --- | --- |
|
|
270
|
-
| `status` | work closes (`OPEN`
|
|
271
|
-
| `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. |
|
|
272
322
|
| `remediation` | the fix is known — usually after the row was logged mid-workflow. |
|
|
273
323
|
| `severity` | re-triage says it was worse or milder than first thought. |
|
|
274
|
-
| `confidence` |
|
|
275
|
-
| `lastConfirmed` |
|
|
276
|
-
| `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.
|
|
329
|
+
|
|
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.
|
|
331
|
+
|
|
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.
|
|
277
334
|
|
|
278
|
-
|
|
335
|
+
`.bkit/friction.jsonl` is excluded, because rows are removed from it (§ Friction Is a Drained Queue) and union would resurrect a drained row.
|
|
279
336
|
|
|
280
|
-
|
|
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`.
|
|
281
338
|
|
|
282
|
-
|
|
283
|
-
- **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.
|
|
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.
|
|
284
340
|
|
|
285
|
-
|
|
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.
|
|
286
342
|
|
|
287
|
-
|
|
343
|
+
**`TRIAGED` is still open work.** Open-entry counts (the audit debt lens, the age report) test `status != "CLOSED"`. Only `CLOSED` is done.
|
|
288
344
|
|
|
289
|
-
|
|
345
|
+
The ladder is not used on `knowledge` or `decision`: both use `ACTIVE` / `SUPERSEDED`. An absent `status` = `ACTIVE`.
|
|
290
346
|
|
|
291
|
-
|
|
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.
|
|
292
348
|
|
|
293
|
-
|
|
349
|
+
Readers count entities, never lines, so `fold` first.
|
|
294
350
|
|
|
295
|
-
|
|
351
|
+
## Compaction
|
|
296
352
|
|
|
297
|
-
|
|
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:
|
|
298
354
|
|
|
299
|
-
|
|
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.
|
|
300
363
|
|
|
301
364
|
## These Ledgers Are Inputs, Not a Diary
|
|
302
365
|
|
|
303
|
-
`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:
|
|
304
367
|
|
|
305
|
-
- **Before designing or planning
|
|
306
|
-
- **On a triage sweep
|
|
307
|
-
- **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.
|
|
308
371
|
|
|
309
|
-
Rank existing
|
|
372
|
+
Rank the existing entries `severity: CRITICAL` first, then by oldest `firstTs` (`ts` when absent).
|
|
310
373
|
|
|
311
374
|
## Identity / Dedup
|
|
312
375
|
|
|
313
|
-
Identity tuple, not bare `ts`:
|
|
376
|
+
Identity is a tuple, not a bare `ts`:
|
|
314
377
|
|
|
315
378
|
<!-- prettier-ignore -->
|
|
316
379
|
| Kind | Identity tuple |
|
|
@@ -320,14 +383,14 @@ Identity tuple, not bare `ts`:
|
|
|
320
383
|
| `counter` | `(repo, by.workflow, run.parentSha, counter.name)` |
|
|
321
384
|
| `friction` \| `deferral` \| `failure` \| `knowledge` \| `decision` \| `feature` \| `chat` \| `run` | `(kind, repo, key)` |
|
|
322
385
|
|
|
323
|
-
|
|
386
|
+
An identity match means the same thing, not an automatic skip:
|
|
324
387
|
|
|
325
|
-
- **Nothing changed**
|
|
326
|
-
- **Something changed**
|
|
388
|
+
- **Nothing changed** → skip.
|
|
389
|
+
- **Something changed** → append (§ Updating a Row).
|
|
327
390
|
|
|
328
391
|
## `engine-action` rows
|
|
329
392
|
|
|
330
|
-
|
|
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.
|
|
331
394
|
|
|
332
395
|
<!-- prettier-ignore -->
|
|
333
396
|
| Field | Value |
|
|
@@ -345,15 +408,15 @@ Not a ledger: a row in a run's `status.jsonl` (`.bkit/workflows.md` § `status.j
|
|
|
345
408
|
|
|
346
409
|
## Versioning
|
|
347
410
|
|
|
348
|
-
`schema: 3` = row format
|
|
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.
|
|
349
412
|
|
|
350
|
-
- **Readers normalize every row:** `normalize()` in `.bkit/core/engine/ledgers/telemetry.ts` returns a `schema` row as is
|
|
351
|
-
- **No version gating:**
|
|
352
|
-
- **Migration:** `bkit install` / `bkit upgrade` rewrite each ledger line without `schema` through `normalize()`, in place.
|
|
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.
|
|
353
416
|
|
|
354
417
|
## Examples
|
|
355
418
|
|
|
356
|
-
|
|
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.
|
|
357
420
|
|
|
358
421
|
`.bkit/stats.jsonl` (`compliance` / `outcome` / `counter`); `harvest/stats.jsonl` (`chat` / `run`):
|
|
359
422
|
|
|
@@ -415,7 +478,7 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
415
478
|
"byModel": { "claude-opus-5-5": { "turns": 120, "tokens": { "input": 900, "cacheWrite": 410000, "cacheRead": 9399100, "output": 52000, "outputEst": 48000, "read": 9810000 } } },
|
|
416
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 } } } }
|
|
417
480
|
},
|
|
418
|
-
"agents": { "total": { "n": 1, "errors": 2 }, "byAgent": { "bkit-build-plan-
|
|
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 } } } },
|
|
419
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 },
|
|
420
483
|
"scan": { "files": 5, "bytes": 4812345, "settled": true, "tokensRecorded": true }
|
|
421
484
|
}
|
|
@@ -431,9 +494,9 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
431
494
|
"time": { "start": 1718900000000, "end": 1718910000000, "totalMinutes": 166.7, "activeMinutes": 98.4, "activeFrom": { "chats": 1, "bytes": 4812345 }, "lastActivity": 1718910000000 },
|
|
432
495
|
"ending": "done",
|
|
433
496
|
"ci": [{ "status": "dispatched", "reason": null, "attempts": 1 }],
|
|
434
|
-
"steps": { "total": { "n": 6, "totalMinutes": 63.7, "activeMinutes": 45.2 }, "byStep": { "build-plan-
|
|
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 } } },
|
|
435
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 },
|
|
436
|
-
"build": { "verify": [{ "group": 1, "attempt": 1, "verdict": "FAIL", "failures": 2
|
|
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 },
|
|
437
500
|
"scan": { "rows": 31, "afterEnd": 0, "settled": true }
|
|
438
501
|
}
|
|
439
502
|
```
|
|
@@ -449,12 +512,12 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
449
512
|
"key": "ship-dev-commit-blocked-by-pre-commit-hook",
|
|
450
513
|
"repo": "cbartens/bkit",
|
|
451
514
|
"bkit": { "version": "5.6.0" },
|
|
452
|
-
"by": { "workflow": "ship", "step": "ship-
|
|
515
|
+
"by": { "workflow": "ship", "step": "ship-bookkeeping-push" },
|
|
453
516
|
"category": "tool-failure",
|
|
454
517
|
"scope": "bkit-repo",
|
|
455
518
|
"severity": "HIGH",
|
|
456
|
-
"summary": "ship
|
|
457
|
-
"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",
|
|
458
521
|
"remediation": "commit via a temp branch (docs/ship-{FID}) from dev in a temp worktree, then FF-merge dev",
|
|
459
522
|
"source": "orchestrator",
|
|
460
523
|
"status": "OPEN",
|
|
@@ -476,7 +539,7 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
476
539
|
"key": "pnpm-tag-drop-readme-note",
|
|
477
540
|
"repo": "cbartens/bkit",
|
|
478
541
|
"bkit": { "version": "5.6.0" },
|
|
479
|
-
"by": { "workflow": "design", "step": "design-
|
|
542
|
+
"by": { "workflow": "design", "step": "design-generate", "subagent": "bkit-design-generate", "model": "claude-opus-5-5" },
|
|
480
543
|
"type": "issue",
|
|
481
544
|
"category": "infra",
|
|
482
545
|
"severity": "LOW",
|
|
@@ -501,7 +564,7 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
501
564
|
"key": "hook-git-dir-leaks-into-temp-repo-tests",
|
|
502
565
|
"repo": "cbartens/bkit",
|
|
503
566
|
"bkit": { "version": "5.6.0" },
|
|
504
|
-
"by": { "workflow": "debug", "step": "debug-diagnose", "subagent": "bkit-debug-failure-diagnose", "model": "claude-opus-
|
|
567
|
+
"by": { "workflow": "debug", "step": "debug-failure-diagnose", "subagent": "bkit-debug-failure-diagnose", "model": "claude-opus-5-5" },
|
|
505
568
|
"category": "tooling",
|
|
506
569
|
"summary": "Tests run from a git hook act on the real repo",
|
|
507
570
|
"severity": "HIGH",
|
|
@@ -524,7 +587,7 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
524
587
|
"key": "gh-mcp-401-after-token-rotation",
|
|
525
588
|
"repo": "cbartens/bkit",
|
|
526
589
|
"bkit": { "version": "5.6.0" },
|
|
527
|
-
"by": { "workflow": "debug", "step": "debug-remediate", "subagent": "bkit-debug-failure-remediate", "model": "claude-sonnet-
|
|
590
|
+
"by": { "workflow": "debug", "step": "debug-failure-remediate", "subagent": "bkit-debug-failure-remediate", "model": "claude-sonnet-5-5" },
|
|
528
591
|
"summary": "GitHub MCP / gh 401 immediately after a token rotation",
|
|
529
592
|
"description": "401 from the GitHub MCP server or gh despite a freshly-rotated, valid, correctly-scoped PAT in .bkit/.env",
|
|
530
593
|
"rootCause": "the MCP server captures GH_MCP_TOKEN at process launch, so a mid-session rotation leaves it holding the dead token",
|
|
@@ -545,7 +608,7 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
|
|
|
545
608
|
"key": "bkit-distribution-via-npmjs",
|
|
546
609
|
"repo": "cbartens/bkit",
|
|
547
610
|
"bkit": { "version": "5.6.0" },
|
|
548
|
-
"by": { "workflow": "plan", "step": "plan-generate", "subagent": "bkit-plan-generate", "model": "claude-opus-
|
|
611
|
+
"by": { "workflow": "plan", "step": "plan-generate", "subagent": "bkit-plan-generate", "model": "claude-opus-5-5" },
|
|
549
612
|
"summary": "publish @cbartens/bkit publicly on npmjs",
|
|
550
613
|
"description": "publish @cbartens/bkit publicly on npmjs; consumers install with no registry mapping, PAT, or CI/Vercel env",
|
|
551
614
|
"rationale": "public install needs no registry mapping or token; release.yml publishes from CI via npm OIDC trusted publishing",
|