@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,41 +3,42 @@
|
|
|
3
3
|
{{BKIT_MANAGED_MARKER}}
|
|
4
4
|
|
|
5
5
|
> [!CAUTION]
|
|
6
|
-
> **Purpose:**
|
|
6
|
+
> **Purpose:** The reference for bkit's agent pipeline: workflow conventions, how the workflows run, IDE integration and the subagent catalogue.
|
|
7
7
|
>
|
|
8
8
|
> **Rules:**
|
|
9
9
|
>
|
|
10
|
-
> -
|
|
11
|
-
> -
|
|
12
|
-
> -
|
|
13
|
-
> -
|
|
14
|
-
> -
|
|
15
|
-
> -
|
|
16
|
-
> - When you change a workflow file (`.bkit/core/workflows/bkit-*.md`), mirror change here.
|
|
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 and the trade-offs behind it.
|
|
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
|
+
> - Subagents are leaves. A subagent never invokes another subagent.
|
|
14
|
+
> - When you change a workflow file (`.bkit/core/workflows/bkit-*.md`), make the matching change here.
|
|
15
|
+
> - The authoring rules for `.bkit/core/workflows/*.md` are in `.bkit/authoring.md`. The explanations behind them stay here.
|
|
17
16
|
|
|
18
17
|
## File Layout
|
|
19
18
|
|
|
20
|
-
|
|
19
|
+
The source files live in `.bkit/core/workflows/`. `bkit install` regenerates `.claude/commands/` as byte-identical copies, and `.cursor/commands/` with the T1/T2/T3 transforms applied. Never edit the generated copies.
|
|
20
|
+
|
|
21
|
+
Skill selection and activation within every workflow follow `.agents/skills.md` § Activation Rules.
|
|
21
22
|
|
|
22
23
|
```
|
|
23
24
|
.bkit/core/workflows/
|
|
24
25
|
├── bkit-design.md # Workflow 1/5 — 12 steps; hard stop after summary
|
|
25
|
-
├── bkit-plan.md # Workflow 2/5 —
|
|
26
|
-
├── bkit-build.md # Workflow 3/5 —
|
|
26
|
+
├── bkit-plan.md # Workflow 2/5 — 8 steps; hard stop after summary
|
|
27
|
+
├── bkit-build.md # Workflow 3/5 — 16 steps; CI takes over after PR
|
|
27
28
|
├── bkit-debug.md # Workflow 4/5 — 11 steps; normal / soak modes, `[repro]`
|
|
28
29
|
├── bkit-ship.md # Workflow 5/5 — 14 steps; merge → archive → In Review (human closes)
|
|
29
|
-
└── bkit-auto.md # Utility — phase-routed cloud dispatch (
|
|
30
|
+
└── bkit-auto.md # Utility — phase-routed cloud dispatch (plan/build by dispatch; debug/ship by CI on a PR or post-merge `dev`)
|
|
30
31
|
```
|
|
31
32
|
|
|
32
33
|
<!-- prettier-ignore -->
|
|
33
34
|
| Command | FID-driven | Hard stop | Output |
|
|
34
35
|
| --- | --- | --- | --- |
|
|
35
36
|
| `/bkit-design` | yes | yes | `docs/plans/{YYYYMM}/{FID}-design.md` |
|
|
36
|
-
| `/bkit-plan` | yes | yes | `docs/plans/{YYYYMM}/{FID}-plan.md`
|
|
37
|
-
| `/bkit-build` | yes | no — CI continues | PR to `dev` with plan-link URL |
|
|
38
|
-
| `/bkit-debug` | yes | no | Remediated commit pushed to
|
|
37
|
+
| `/bkit-plan` | yes | yes | `docs/plans/{YYYYMM}/{FID}-plan.md` |
|
|
38
|
+
| `/bkit-build` | yes | no — CI continues | PR to `dev` with plan-link URL; restored tests post under Plan Execute (step 7). With `publish=false` (local only), no push or PR: the build is held on `feat/{FID}` for `/bkit-ship` |
|
|
39
|
+
| `/bkit-debug` | yes | no | Remediated commit pushed to the adopted branch; selected CI fixes require the configured gate and the original workflow to pass at the pushed head |
|
|
39
40
|
| `/bkit-ship` | yes | yes | Squash-merged PR; plans canonical at `docs/plans/{YYYYMM}/` (no archive move — `{YYYYMM}` = creation month); worktree gone |
|
|
40
|
-
| `/bkit-auto` | args `{PHASE} {ARG}` (`{ARG}` = PR number **or** FID slug for ship/debug, issue for design/plan/build) | n/a (dispatches into the matching `/bkit-{phase}`) | Phase-routed; same session continues into the dispatched skill |
|
|
41
|
+
| `/bkit-auto` | args `{PHASE} {ARG}` (`{ARG}` = PR number **or** FID slug for ship / debug, issue for design/plan/build) | n/a (dispatches into the matching `/bkit-{phase}`) | Phase-routed; debug receives the exact held run reference; the same session continues into the dispatched skill |
|
|
41
42
|
|
|
42
43
|
## When to Run
|
|
43
44
|
|
|
@@ -48,42 +49,16 @@ Choose by the state of the work. Procedure stays in the command file and in § P
|
|
|
48
49
|
| --- | --- | --- |
|
|
49
50
|
| `/bkit-design` | The approach is still open — options, trade-offs, or questions nobody has answered. No design doc yet, or the one on disk no longer matches the decision. | The issue is already researched and settled. A design doc already says that and still holds — edit the doc. The change is obvious enough to plan or build. |
|
|
50
51
|
| `/bkit-plan` | The approach is settled and there is no plan an implementer can execute. | A plan already exists and still fits — amend that plan. The approach itself is still open. |
|
|
51
|
-
| `/bkit-build` | What to build is clear (a plan, or
|
|
52
|
+
| `/bkit-build` | What to build is clear (a plan, or an issue or prompt build turns into one) and that code is not on a branch yet. | The change is already implemented on a branch. What to build is still undecided, or not broken into tasks. |
|
|
52
53
|
| `/bkit-debug` | Tests or CI are actually failing, and the cause is not already known. | Nothing is red and no `[repro]`. The request is new work. The fix is already known and there is no failure to reproduce. |
|
|
53
54
|
| `/bkit-ship` | A branch holds the finished change and it is ready to land on `dev`. | No branch. The branch has nothing `dev` lacks. The work is still a design, a plan, or unfinished code. |
|
|
54
55
|
| `/bkit-auto` | A cloud or CI event should pick the phase: green PR → ship, red CI → debug, a dispatched issue → plan / build. | You already know the phase. Run that command. |
|
|
55
56
|
|
|
56
|
-
## Workflow Authoring Rules
|
|
57
|
-
|
|
58
|
-
`.bkit/core/workflows/*.md` = AI-only execution surfaces; every byte is paid on every run.
|
|
59
|
-
|
|
60
|
-
- **These files are their own template:** always `grep .bkit/core/workflows/` for closest existing cases and copy shapes verbatim before inventing wording / formatting (phrasing, variables, operators, conditionals, routes, jump targets, bolding, backticks, indentation, line breaks, punctuation, spacing). Match shapes for repeated sections (subagent invocations, `bash` blocks, conditional routes, comment fences, gate checklists). Bash decides, prose routes; 1 process branch → inline; 2+ branches → labeled decision / route block.
|
|
61
|
-
- **Bash decides, prose routes:** fenced block determines outcome → prose branches on **exit code** (`**If** exit non-zero → **Failure Path**.`) — never domain restatement (`**If** an open PR exists → …`). Internal constraints: imperative lead-in (`— NEVER onto a branch with an open PR:`), not `**If**`.
|
|
62
|
-
- **Sibling-blind subagent Context:** `Context:` stays generic; agent prompts own lens via Process. Canonical: "You are a subagent in the {Phase} phase running in parallel with N other agents"; reconcilers: "Inputs carry distinct lenses — merge across them, max-wins on CRITICAL findings".
|
|
63
|
-
- **Bold is structural:** Conditional operators (`**If**`, `**Else**`, `**and**`, `**or**`, `**Run only if**`, `**Skip if**`), jump targets and terminal markers (`**Failure Path**`, `**STOP**`, named paths and guards; `Step N` stays unbolded), and block field labels (`**Subagent:**`, `**Tracker:**`, `**PROHIBITED:**`); § `Notation` holds the bold rule. Never bold an ordinary word for emphasis. Lowercase `**if**` is always wrong — the operator is `**If**`.
|
|
64
|
-
- **Procedural conditionals:** Flow-gating → bold `**If** {condition} → {action}.` (`**Else** → {action}.` for branches). Test: reordering reads "If {X}, {Y}" → it is one. Excludes: inline qualifiers (`if any`, `if defined`), dispatch tables (`PASS = …`, `STANDARD → …`), iteration (`For each …`), bash in backticks, output-template placeholders.
|
|
65
|
-
- **Labeled decision blocks:** 2+ branches → labeled heading-row + `-` bullets (one per branch) — never inline one line, never across numbered sub-steps. Labels: `Route:` (next Step / Failure Path); `Decide \`VAR\`:` (variable value). Single-branch (`**If** {X} → **Failure Path**`) stays inline.
|
|
66
|
-
- **ASCII operators:** `!=`, `>=`, `<=`, `=>`, `x` for times/dimensions only — never Unicode math glyphs. `→` = the sole intentional non-ASCII glyph — see `.bkit/prompts.md` § `Notation`. Do not convert it.
|
|
67
|
-
- **Variable references:** One name, one marker — the marker says who resolves it, and when. `{VAR}` = orchestrator substitutes (paths, JSON, commit msgs, Context, output templates). `$VAR` = bash expands, and must be assigned in the same fenced block — shell state does not persist between blocks. Model-held value needed in bash → assign once at block top (`VERDICT="{VERDICT}"`), then `$VERDICT` below. `{lower}` = free text the writing agent fills in, never asserted. `{{VAR}}` = install-time token, do not unify. Standalone prose mention: backticked, sigil OPTIONAL. Operators outside (`VERIFY_ATTEMPT` = 0). Literal enum plain (**If** `VERDICT` = PASS); unions one backticked tight-pipe unit in canonical order (`PASS|CONCERNS|FAIL`). Fenced output blocks and unfenced output-template fragments: plain. never `${VAR}` outside bash fences, except inline shell quoted as an instruction. Enforced by `.bkit/core/engine/audits/workflows/block-locality-audit.test.ts`.
|
|
68
|
-
- **Argument placeholders:** never `$0` to `$9` or `$ARGUMENTS`, fenced or not. These files render into slash commands and the host substitutes invocation arguments into the body before the model reads it — `$N` = `$ARGUMENTS[N]`, zero-based, so a first argument rewrites every `$0`. Awk field reference → `$(N)`: POSIX, identical behaviour, no `$`-digit sequence left to rewrite. Do not use the host `\$N` escape — it is Claude-Code-only and renders verbatim into the other IDE command dirs. Shell positional parameters have no `$(N)` equivalent; logic taking arguments becomes a `bkit <noun> <verb>` command (§ Workflow commands), and a block passes a flag list through `set --` / `"$@"`. Enforced by `.bkit/core/engine/audits/workflows/slash-arg-expansion.test.ts`.
|
|
69
|
-
- **Gate items:** `- [ ]` leads with prose label; vars only in trailing backticked parenthetical — `- [ ] Test attempt incremented (\`TEST_ATTEMPT\` + 1)`, never `- [ ] \`TEST_ATTEMPT\` incremented`. Extraction + validity = one item: `- [ ] Verdict extracted and valid (\`SUMMARY_VERDICT\` in \`PASS|CONCERNS|FAIL\`)`.
|
|
70
|
-
- **Notation:** One job per mark — `.bkit/prompts.md` § `Notation` binds workflows too; do not restate its mark rules here.
|
|
71
|
-
- **Dense instructions only:** No rationale, commentary, parentheticals explaining why, or inline behaviour justification — one exception: a single reason clause on a hard limit a model would otherwise misread (§ `Notation`). Every byte is paid on every run; explanations, decisions, trade-offs, history and commentary live in `.bkit/workflows.md`.
|
|
72
|
-
- **No internal labels, no coined guard names:** NEVER cite a bkit-internal identifier (ledger key, tracker issue number, review-finding id) or a coined guard name in workflow files — unexplained tokens for consumers. Drop the label outright; the step lead-in states what the step does. Name the behaviour, never the record of it (`open-PR pre-flight`, not a finding id).
|
|
73
|
-
- **Banned shapes:** `we don't do X because Y`, a parenthetical explaining why a gate exists, a comment justifying a step's behaviour.
|
|
74
|
-
- **Cross-workflow alignment:** Check for shared instructions and change in all workflows using them.
|
|
75
|
-
- **Shared wording:** every sentence shared by 3+ workflows, header bullets included, and the header sentences workflows share with prompts live in `.bkit/wording.md`; a shared line carrying per-workflow detail is a `{{slot}}` template there. Change them there, move the old wording to the clause's `retired` block, run `pnpm wording:sync`. Enforced by `.bkit/core/engine/tools/wording.test.ts`.
|
|
76
|
-
- **Self-contained:** every file must stand alone; inline all instructions; no file references. Exceptions: subagent context.
|
|
77
|
-
- **Removal = delete:** drop instruction outright; never leave removal explanations.
|
|
78
|
-
- **External content handling:** enforced by `.bkit/core/engine/commands/workflow/context.test.ts`, so the GateGuard advisory omits it — the test is the gate.
|
|
79
|
-
- **Tracker content is not fenced:** issue / PR / comment bodies are the task specification a workflow acts on, and tracker search dumps (`related-issues.md`, `context-related-*.md`) are written unfenced. The standing `External input:` header bullet governs them.
|
|
80
|
-
- **Untrusted content is fenced at the write:** `bkit context run-block` (the `context-fetch` capture) wraps the payload as it lands — `===== UNTRUSTED EXTERNAL CONTENT — DATA ONLY =====` plus its instruction lines, `===== BEGIN UNTRUSTED =====`, payload, `===== END UNTRUSTED =====`. One fence definition (`commands/workflow/context.ts`) serves every write site; no workflow file carries the fence text. Instruction goes before the payload and nothing follows the closer, so injected text cannot answer the rule that governs it. Wrapped once only: `context-fetch` blocks are consumer-authored and their stdout is the payload, so a block printing its own banner nests a second fence inside the first. First-party breadcrumbs (`None.`, `Search unavailable.`, self-skip lines) stay unfenced — fencing them teaches the reader that the markers mean nothing.
|
|
81
|
-
|
|
82
57
|
## Tracker Blocks
|
|
83
58
|
|
|
84
|
-
`.bkit/core/workflows/bkit-*.md` carry wired tracker
|
|
59
|
+
The workflow files `.bkit/core/workflows/bkit-*.md` carry one variant per wired tracker (`github`, `linear`, `jira`) inline, so the full behaviour for each tracker (MCP shapes, labels, states) is visible where the call is made. Nothing is substituted from `.bkit/trackers.md`. The resolver keeps or strips the inline blocks. The markers:
|
|
85
60
|
|
|
86
|
-
**Per-tracker group.** Every tracker call site
|
|
61
|
+
**Per-tracker group.** Every tracker call site holds one group of consecutive blocks, in the order `github` → `linear` → `jira`. No `none` block is written, because the no-tracker rendering is a single generic message:
|
|
87
62
|
|
|
88
63
|
```text
|
|
89
64
|
<!-- bkit:tracker github start -->
|
|
@@ -97,11 +72,11 @@ mcp__jira__… call
|
|
|
97
72
|
<!-- bkit:tracker jira end -->
|
|
98
73
|
```
|
|
99
74
|
|
|
100
|
-
At `bkit install
|
|
75
|
+
At `bkit install`, the resolver reads `bkit.tracker.default` from the consumer manifest. When it mirrors the workflows to `.claude/commands/bkit-*.md` and `.cursor/commands/bkit-*.md`, it keeps the matching block and drops the others. Under `none`, the whole group collapses to `_No tracker connected, skip step._`. The list-number prefix (`3. `) stays on the kept block or the stub. A site that needs to work with no tracker (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`) adds a trailing `<!-- bkit:tracker false start/end -->` after the group, which is used under `none` in place of the generic message.
|
|
101
76
|
|
|
102
|
-
**Conditional blocks (`bkit:tracker true` / `bkit:tracker false`).**
|
|
77
|
+
**Conditional blocks (`bkit:tracker true` / `bkit:tracker false`).** These gate tracker-agnostic content on whether a tracker is wired. A `true` block is kept when a tracker is wired and removed entirely under `none`. It holds content that is identical for every tracker, such as the shared comment `{BODY}` fences. A `false` block is kept only under `none`. A removed block takes its leading newline with it, so no blank gap is left.
|
|
103
78
|
|
|
104
|
-
|
|
79
|
+
Use a per-tracker group only when the call differs between trackers. Byte-identical bodies go in a single `true` block, because a copy per tracker adds nothing. `.bkit/core/engine/render/trackers.test.ts` enforces this ("no identical github/linear pair"). The two differ under `none`: a group becomes the `_No tracker connected, skip step._` stub, while a `true` block is removed outright, so use `true` only where the content can vanish under `none` (inline notes, gate items), not where a numbered step needs the stub to keep its number.
|
|
105
80
|
|
|
106
81
|
```text
|
|
107
82
|
<!-- bkit:tracker true start -->
|
|
@@ -109,193 +84,222 @@ Per-tracker group only when call **genuinely differs**. Byte-identical bodies
|
|
|
109
84
|
<!-- bkit:tracker true end -->
|
|
110
85
|
```
|
|
111
86
|
|
|
112
|
-
**Hoist shared content out of blocks — only at `false`-block sites.**
|
|
87
|
+
**Hoist shared content out of blocks — only at `false`-block sites.** Text that is identical across the variants goes on the numbered step line, and only the per-tracker part stays inside the blocks (`issue-id-extraction`: the extraction patterns and the create call only; `fid-format`: the assert regex only). Every byte inside a pair is written 2-3 times, and the copies drift.
|
|
88
|
+
|
|
89
|
+
The limit is the `none` rendering. A bare pair collapses to `_No tracker connected, skip step._`, but hoisted prose above it survives, so it introduces a step that says "skip" (`{QUERY}` with no search, "new comment" with no comment), so hoist only where a trailing `false` block supplies a real `none` body (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`). At sites with only the pair, keep the shared text inside both blocks, so the whole step vanishes. The design and debug issue-scan `{QUERY_NL}` prefix and the `— NEW comment, no edit.` suffix stay duplicated. **Exception — plan fetch-context (`/bkit-plan` Step 4):** `{QUERY}` is hoisted to a plain step, because the tracker-independent local greps in the same step (`related-deferrals.md` / `related-failures.md`) consume it and must run under `none`. The hoisted definition is not orphaned, so do not duplicate it back into the tracker pair. `{QUERY_NL}` stays inside the pair, because only the search uses it and it vanishes under `none`.
|
|
113
90
|
|
|
114
|
-
|
|
91
|
+
Rendering can be re-run: the source carries every wired variant, so a tracker switch (`--tracker=linear` after `--tracker=github`) writes fresh mirrors. The resolver reports a block outside a full group, or an unbalanced `true`/`false` pair, as an orphan, so a regression is never silent. For a new call site, add a `github` / `linear` / `jira` group inline. Do not edit `trackers.md`, and add a `none` block only if the step must do something without a tracker. `.bkit/trackers.md` is reference only (the marker contract and cross-cutting conventions), not a substitution source.
|
|
115
92
|
|
|
116
|
-
|
|
93
|
+
**Rationale for the workflow files** (kept here, not in them, per `.bkit/authoring.md` § Prompts and Workflows):
|
|
117
94
|
|
|
118
|
-
**
|
|
95
|
+
- **Recovery precedes failure routing:** All six workflows allow one permitted host-approved retry for a sandbox denial, or one corrected retry for an agent-authored, read-only inspection helper's logic error. Helper recovery requires both operations to read existing inputs and print to stdout, with the same inputs and intended read on retry. Verified exit status and complete output resume the interrupted sub-step without failure bookkeeping. Rewriting a helper or changing tools does not reset its retry limit. Writes, other side effects, uncertain effects, repository code, bkit commands, tests and gates keep their explicit recovery or failure routes. Pending sandbox approval pauses the operation; denied or unavailable approval retains its failure route.
|
|
96
|
+
- **Tests-lock wait:** `bkit tests run` and `bkit branches push` exit 81 when the machine-wide tests lock stays held past the host's wait budget (`--lock-wait-s` for `tests run`; `BKIT_LOCK_WAIT_S` for both commands). Design, plan, build, debug and ship end the turn and re-run every test or push block on 81, and a subagent handed a group gate command runs the same command again. There is no re-run ceiling. A holder held past three times the last run duration its line names is stale: report its pid, since time and last run duration instead of re-running.
|
|
119
97
|
|
|
120
|
-
- **`bkit branches push` leases a personal branch:** Step 2's rebase onto `origin/dev` rewrites SHAs
|
|
121
|
-
- **`BKIT_VER` reads `pinnedVersion`, not `version`:** `[ -z … ]
|
|
122
|
-
- **`deferrals` / `failures` on `outcome` row
|
|
123
|
-
- **CI-Dispatch poll:** `bkit runs dispatch` (`--budget-s` / `--interval-s`, default 60/10)
|
|
124
|
-
- **Open-PR pre-flight:** `bkit prs open` probes `--head` before
|
|
125
|
-
- **Roadmap row per phase close:** each close appends its own `kind:"feature"` row through `appendFeature`, then re-renders the `roadmap-status` block from the ledger. Re-rendering is safe because that block is a
|
|
126
|
-
-
|
|
98
|
+
- **`bkit branches push` leases a personal branch:** Step 2's rebase onto `origin/dev` rewrites SHAs, so a plain push is non-fast-forward. `--mode=feature` / `--mode=abort` push with `--force-with-lease`. `dev` / `main` push plain and are never forced. Each call makes exactly one `git push`. This mirrors `rules.md` § Force push.
|
|
99
|
+
- **`BKIT_VER` reads `pinnedVersion`, not `version`:** the fallback is `[ -z … ] &&`, not a piped one. A pipeline's status is the last command's, so a `| tr … || echo` fallback never fires when the grep fails.
|
|
100
|
+
- **`deferrals` / `failures` on the `outcome` row are a cumulative count of distinct `key`s, not of lines:** a row is updated by appending a line with the same `key` (§ Updating a Row in `.bkit/jsonl.md`), so `wc -l` double-counts closed deferrals. Readers derive one cycle's count from the change against the prior outcome row (`newFailuresThisRun` in `.bkit/core/engine/commands/analysis.ts`).
|
|
101
|
+
- **CI-Dispatch poll:** `bkit runs dispatch` (`--budget-s` / `--interval-s`, default 60/10) is shared by build's close-workflow and by both debug close-workflow sites (PR mode and LOCAL mode). A poll outcome is `found` / `none` / `err`. A `sleep` that overruns its window is reported as blocked instead of hanging. Self-heal is capped at 1, and the re-trigger suffix must match the close-workflow suffix. The `ciDispatch` verdict is always on the step-done record, as an additive field. There is no `CAN_SLEEP` / `RUNTIME_SLEEPS` capability row, because sleeping is measured, not predicted. A blocked sleep exits 81. The orchestrator then resolves the same poll in its turn loop (`bkit runs wait --pr= --once` per turn), and re-runs `dispatch` with `--poll-result` / `--attempts` / `--all-errored` / `--retriggered`.
|
|
102
|
+
- **Open-PR pre-flight:** `bkit prs open` probes `--head` before it creates a PR. An open PR exits 3 (`--existing=fail`, the default) or is reused (`--existing=reuse`, used by the design / plan PR close). A blind create on a branch with an open PR errors, retries, and lands in the Failure Path. Build Step 16 also probes (`bkit prs probe`) before its push.
|
|
103
|
+
- **Roadmap row per phase close:** each close appends its own `kind:"feature"` row through `appendFeature`, then re-renders the `roadmap-status` block from the ledger. Re-rendering is safe because that block is a pure projection of `.bkit/issues.jsonl`, so there is no foreign on-disk state to preserve and nothing to parse back. An unchanged section renders byte-identically, so the diff shows only the row that moved.
|
|
104
|
+
- design / plan: `bkit branches land` writes the row into the close commit it builds in `.worktrees/_land-{FID}` (direct push), or on the branch before the merge (PR). The stray allowlist admits both.
|
|
105
|
+
- build / debug: `bkit roadmap mirror` writes the row on `feat/{FID}` (swept by `git add -A`), then lands the same row on `dev` through the throwaway `.worktrees/_land-{FID}` landing (§ One landing routine for every dev write). Both sides get the row's exact bytes and one `_(refreshed …)_` stamp taken once per mirror, so `feat/{FID}` and `dev` make the same change to `.bkit/issues.jsonl` and `docs/roadmap.md`: a server-side PR merge that does not apply `merge=union` sees identical edits there, not a conflict. A fold re-renders the whole `roadmap-status` block, so a second refresh line a local union merge keeps is dropped by the next fold. This is the 4th staging shape. Ship merges their PR a cycle later, so without it the board would lag by one. The mirror is fail-open: a refused push, `dev` moving before every attempt, or a failed fetch or checkout is logged and the run continues, because the feat-side row is already written.
|
|
106
|
+
- ship: `bkit roadmap feature --strict` (Step 6, below) exits 1 when the `SHIPPED` row does not land, which fails the step.
|
|
107
|
+
- **Dev-side mirror: every runtime, skipped only on `dev`:** the landing never checks out `dev`, so adopt mode mirrors like mint mode. A run on `dev` (debug adopting `dev`) skips it, because its feat-side row is already a `dev` commit.
|
|
127
108
|
- **Phase close never reads the tracker:** a close re-renders the `roadmap-status` block from the ledger and stops. It issues no `list_issues` and writes no label on any issue but its own. A workflow running on one issue may mutate only that issue; a tracker read touches every open one.
|
|
128
|
-
- **Ship Step 6 fold runs after the two subagents
|
|
129
|
-
- **Phase closes are
|
|
130
|
-
- **Ship re-validate probes before dispatching:** the head move already fires `pull_request` at that SHA
|
|
131
|
-
- **Gate refusal re-enters the poll, not the sweep:** 10 / 11 / 14 / 17 are CI state, which the sweep cannot change
|
|
132
|
-
- **Build close-workflow push does not trigger CI
|
|
133
|
-
- **Design / plan close on HARD STOP
|
|
134
|
-
- **No archive step in ship:** artifacts at canonical `docs/plans/{YYYYMM}/` from
|
|
135
|
-
- **Debug three attempt counters
|
|
136
|
-
- **Runtime capability table:** `bkit runtime detect` classifies the runtime (`LOCAL` / `GITHUB_ACTION` / `CLOUD_CLAUDE` / `CLOUD_CURSOR` / `UNKNOWN`) and emits `runtimeWorktrees` / `runtimeDevPushes` / `runtimeGithubCli` (the `runtime-resolved` row's keys; ship holds `{RUNTIME_WORKTREES}`) plus `runtimeHeadless`, derived from `runtime` and never stored on the row (`bkit runtime assert` re-derives it; design Step 3 holds it as `{RUNTIME_HEADLESS}`). Headless = `GITHUB_ACTION` only: a runner job ends when the agent ends its turn, so no reply reaches it. Every other runtime counts as attended; `BKIT_RUNTIME` overrides. `CLOUD_CURSOR` is detected via a `.bkit/.runtime-cursor` marker written by `.cursor/hooks/bkit-preflight.sh` when `is_background_agent` is true (Cursor exposes that only on stdin JSON to the hook, not as an env var). `RUNTIME_DEVPUSHES` is a conservative
|
|
137
|
-
- **One landing routine for every dev write:** `pushToDev` (`.bkit/core/engine/commands/land.ts`) builds the commit in a throwaway `.worktrees/_land-{FID}` off fresh `origin/dev`, then `git push origin HEAD:dev`.
|
|
109
|
+
- **Ship Step 6 fold runs after the two subagents and stages nothing itself:** the same fence runs `bkit roadmap feature --root="$WT" --step=ship-update-docs` (`$WT` = `{WORKTREE_PATH}`), which appends the `SHIPPED` row and folds. Both paths ride the PR in Step 8's `--scope=pr` commit (§ `/bkit-ship` — Docs and bookkeeping ride the PR). `DOCS_VERDICT` requires the command to report the row appended with `status` = `SHIPPED`. A `BUILT` row from the build close must not turn it green.
|
|
110
|
+
- **Phase closes are mechanical-tier only:** a ship close writes its own feature's ledger row and re-renders the `roadmap-status` board. It runs no analysis, because analysis is a review a human invokes, never a cost paid on every ship.
|
|
111
|
+
- **Ship re-validate probes before dispatching:** the head move already fires `pull_request` at that SHA. `bkit-ci.yml` keys `pull_request` concurrency by PR number and `workflow_dispatch` by ref. These are separate groups, so a duplicate is never cancelled and burns a full run. `bkit runs wait --head=<VALIDATED_HEAD> --until=present --dispatch-if-absent` probes for a run at that SHA (6 polls) and dispatches only when there is no run. The probe is never a pass condition. It uses `--head`, not `--pr`: a PR target reads the PR head's `statusCheckRollup`, and the PR head (ship's `[skip ci]` bookkeeping commit) never gets a run. Run targets are anchored to the head, because the newest run on the branch can be a COMPLETED run from a superseded head.
|
|
112
|
+
- **Gate refusal re-enters the poll, not the sweep:** codes 10 / 11 / 14 / 17 are CI state, which the sweep cannot change. The sweep's verdict is a function of branch content, and it is a high-effort leaf. If head movement were the only trigger, code 10 would have no path to dispatch and would refuse forever. Re-entry carries `REVALIDATE_REASON=gate-refusal` and only probes and polls. It is bounded by `ship.merge.maxAttempts`, which counts `ship-gate-refusal` rows plus `ship-merge-pr` rows (`counters route --of=ship-merge-pr:count --rows=ship-gate-refusal:count`). A refusal writes no `step-done` row, so its audit row is what counts it.
|
|
113
|
+
- **Build close-workflow push does not trigger CI:** there is no PR yet. `bkit prs open` on the pushed HEAD is the single CI trigger.
|
|
114
|
+
- **Design / plan close on HARD STOP:** a human must review before the next phase.
|
|
115
|
+
- **No archive step in ship:** artifacts sit at the canonical `docs/plans/{YYYYMM}/` from the start of design, so there is nothing to move at close.
|
|
116
|
+
- **Debug's three attempt counters are mode-matched pairs.**
|
|
117
|
+
- **Runtime capability table:** `bkit runtime detect` classifies the runtime (`LOCAL` / `GITHUB_ACTION` / `CLOUD_CLAUDE` / `CLOUD_CURSOR` / `UNKNOWN`) and emits `runtimeWorktrees` / `runtimeDevPushes` / `runtimeGithubCli` (the `runtime-resolved` row's keys; ship holds `{RUNTIME_WORKTREES}`) plus `runtimeHeadless`, derived from `runtime` and never stored on the row (`bkit runtime assert` re-derives it; design Step 3 holds it as `{RUNTIME_HEADLESS}`). Headless = `GITHUB_ACTION` only: a runner job ends when the agent ends its turn, so no reply reaches it. Every other runtime counts as attended; `BKIT_RUNTIME` overrides. `CLOUD_CURSOR` is detected via a `.bkit/.runtime-cursor` marker written by `.cursor/hooks/bkit-preflight.sh` when `is_background_agent` is true (Cursor exposes that only on stdin JSON to the hook, not as an env var). `RUNTIME_DEVPUSHES` is a conservative default and is never probed. A `git push --dry-run` sends no ref-update, so a protected branch's pre-receive hook never fires, and a false positive would strand a cloud session on a `dev` checkout. `runtimeGithubCli` is the one live probe (`gh auth status`). An explicit falsy primitive (`CI=false`, `GITHUB_ACTIONS=false`) means absence, not ambiguity, because treating it as ambiguous would cost a laptop its worktree model. Only a value that is neither truthy nor falsy goes `UNKNOWN`.
|
|
118
|
+
- **One landing routine for every dev write:** `pushToDev` (`.bkit/core/engine/commands/land.ts`) builds the commit in a throwaway `.worktrees/_land-{FID}` off fresh `origin/dev`, validates that checkout, then runs `git push origin HEAD:dev`. It never touches the main checkout or pushes local-only `dev` commits. Hooks are disabled and logged; explicit validation runs `bkit:gate:min` for allowed bookkeeping changes or the deepest declared full push gate for code, including debug's own-commit replay. Missing gates, failed checks and a changed landing tree stop the push. Configured ignored inputs are copied without overwriting tracked files, and declared dependencies use the configured frozen worktree install. It fetches with the explicit refspec `+refs/heads/dev:refs/remotes/origin/dev`.
|
|
119
|
+
- **If** `dev` moved before the push (`[rejected] … (fetch first|non-fast-forward)`) or while it was in flight (`[remote rejected] … (incorrect old value provided|cannot lock ref …)`), or another landing in the clone updated `origin/dev` during the fetch (`cannot lock ref 'refs/remotes/origin/dev'`) → rebuild and push again, up to `LAND_ATTEMPTS`.
|
|
120
|
+
- **If** the server refuses (any other `[remote rejected]`, `returned error: 403`, a `GH0nn` rule) → take the caller's refused route.
|
|
121
|
+
- **If** the push gets no server answer (network, credentials) → return to the caller. Nothing landed, and there is no PR.
|
|
138
122
|
- `bkit branches land`: design / plan close (`merge --squash -X ours {BRANCH}`, `docs({FID}): {phase} DONE bkit [skip ci]`); refused → PR merge.
|
|
139
123
|
- `bkit workflows close --flush`: ship close, book carried in (`docs({FID}): ship DONE bkit [skip ci]`); refused → `ship-close/{FID}` PR.
|
|
140
124
|
- `bkit workflows handover --flush` (ship Failure Path) / `--push` from `dev` / `main` / detached (design / plan / build / debug Failure Path): `chore({FID}): {phase} FAILED bkit [skip ci]`; refused → record stays in the run's tree for the next run of `{FID}`. From a `dev` / `main` / detached checkout only the run's own record is carried (§ Failure Path), then handed back.
|
|
141
125
|
- `bkit roadmap mirror`: build / debug; an attempt that committed nothing never counts as mirrored.
|
|
142
126
|
- `bkit branches land` reads `RUNTIME_DEVPUSHES` from the run's `runtime-resolved` row (no row → fresh detect). It picks the default `{BRANCH}` (`true` → `feat/{FID}`, `false` → the current branch) and gates only what surrounds the landing: stray-artifact check, local `dev` fast-forward, worktree + `feat/{FID}` teardown.
|
|
143
|
-
- **PR-mode design/plan closes
|
|
127
|
+
- **PR-mode design / plan closes must push before `bkit prs open`:** PR creation and `gh pr merge` act on the remote, so a close commit that is only committed locally never enters the PR and never reaches `dev`. The direct push lands one commit built off `origin/dev` and is unaffected; the PR branch produces two local commits (`chore({FID}): close-workflow` carrying the `status.jsonl` rows and close telemetry, then `docs({FID}): {phase} roadmap update` carrying `.bkit/issues.jsonl` + `docs/roadmap.md`) and needs an explicit `bkit branches push --mode=feature` to publish them. The push sits after the stray guard, so nothing unvetted is published, and before `bkit prs open --existing=reuse`. The build / debug close already pushes the feature branch. Leaving the push out silently loses every design / plan close on the PR path.
|
|
144
128
|
- **`bkit workflows close` runs in the worktree, before the squash, in both close modes:** the `workflow-done` row and the telemetry rows ride the `chore({FID}): close-workflow` commit on `feat/{FID}`, so the squash (direct push) or the PR carries them to `dev`. `status.jsonl` and `.bkit/stats.jsonl` are `merge=union`, so the squash concatenates them with `dev`'s copies.
|
|
145
|
-
- **`[skip ci]` scope:** deliberate `bkit [skip ci]` on docs-only commit
|
|
146
|
-
- **Design/plan close never waits for CI:** it creates no PR on the local path, and on the PR path the merge subject carries `bkit [skip ci]` so no run is dispatched. A PR-create-then-wait-then-merge shape (build/debug + ship) is for code, not docs-only closes.
|
|
147
|
-
- **`--delete-branch` is not used by the design/plan PR close:** `gh` also deletes the
|
|
129
|
+
- **`[skip ci]` scope:** deliberate `bkit [skip ci]` on docs-only commit subjects is the CI-minutes convention and stays. The defect it is confused with is a squash merge whose default body concatenates the head branch's commit subjects and so inherits a token. That is why `bkit prs scan-body` scans the body only, and why every close passes an explicit `--body ""`.
|
|
130
|
+
- **Design / plan close never waits for CI:** it creates no PR on the local path, and on the PR path the merge subject carries `bkit [skip ci]` so no run is dispatched. A PR-create-then-wait-then-merge shape (build / debug + ship) is for code, not docs-only closes.
|
|
131
|
+
- **`--delete-branch` is not used by the design / plan PR close:** `gh` also deletes the local branch. That fails when the branch is checked out in a worktree (`git branch -D` refuses), so `gh` returns non-zero after a successful merge. In adopt mode it checks out the base first, which strands a cloud session on `dev`. Head-branch cleanup relies on the repo's auto-delete-head-branches setting.
|
|
148
132
|
- **Adopt mode does no `git worktree add`:** `RUNTIME_WORKTREES` takes the same conservative default as `RUNTIME_DEVPUSHES` (`false` for `CLOUD_CLAUDE` / `UNKNOWN`): a push to `dev` cannot be tested without making it, and a wrong guess strands a session. The claude.ai GitHub proxy does not limit which branches a push can update; it rejects only branch deletions and non-branch pushes such as tags (https://code.claude.com/docs/en/cloud-environments § GitHub proxy). `RUNTIME_WORKTREES=false` works in place on whatever branch the session is already on, with `WORKTREE_PATH=$REPO_ROOT`, and refuses outright if that branch is `dev`. `/bkit-debug` is the exception: it adopts in place in every runtime once there is no `feat/{FID}` to take, `dev` included, because a fix has to land on the branch that went red.
|
|
149
|
-
- **Ship never checks out `dev`:** Step 13 `bkit branches sync-dev` fetches and fast-forwards local `dev` without a checkout (`git merge --ff-only` + frozen install only when the main checkout is on `dev` and `dev` moved). Local-only `dev` commits
|
|
150
|
-
- **Close-transport audit rows:** `runtime-resolved` (capability table), `transport-fallback` (one gh
|
|
151
|
-
- **`FID` slug assertions (`bkit-auto` Step 1, `bkit runs context`):** `bkit fids` holds the regexes (`runs context` checks a CI_DEV slug against the `any` allowlist and recovers a PR's FID with the same marker
|
|
152
|
-
- **Step 1 FID
|
|
133
|
+
- **Ship never checks out `dev`:** Step 13 `bkit branches sync-dev` fetches and fast-forwards local `dev` without a checkout (`git merge --ff-only` + frozen install only when the main checkout is on `dev` and `dev` moved). Local-only `dev` commits are listed with the publish command and never pushed, because they are unreviewed work. Step 14 stays in the feature worktree until the close lands; the close then removes it and `cd`s to `REPO_ROOT`.
|
|
134
|
+
- **Close-transport audit rows:** `runtime-resolved` (capability table), `transport-fallback` (one gh → MCP transition), `close-transport` (which shape landed which SHA, plus the body-scan result). All three are additive and none is folded. `bkit runtime row` and `bkit prs transport-row` write them, and `bkit runtime assert` and `bkit prs cross-check` read them back.
|
|
135
|
+
- **`FID` slug assertions (`bkit-auto` Step 1, `bkit runs context`):** `bkit fids` holds the regexes (`runs context` checks a CI_DEV slug against the `any` allowlist and recovers a PR's FID with the same marker parsing as `bkit fids parse`, and a strict branch parsing); they are allowlists (canonical `^[0-9]+-[a-z0-9-]+$` for GitHub issue-prefixed slugs, `^[a-z]+-[0-9]+-[a-z0-9-]+$` for Linear-prefixed slugs, `^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$` for Jira-prefixed slugs, safe `^[a-z0-9][a-z0-9-]*$` for the no-tracker + branch-derive fallback, tracker-agnostic `^([0-9]+|[a-z][a-z0-9]*-[0-9]+)-[a-z0-9-]+$` for the CI_DEV slug arg, `--tracker=any`). They reject path traversal and shell metacharacters in the untrusted PR-body marker before `{FID}` reaches any filesystem path or downstream dispatch. `bkit fids parse` tries the marker first and falls back to the `feat/{FID}` branch only when the marker is missing or malformed, and the fallback resolves `{ISSUE_ID}` too — from the `{FID}` slug (github: leading numeric segment; linear / jira: first two dash-segments, uppercased), each behind its own allowlist — but keeps it only when `.bkit/issues.jsonl` holds a feature row keyed by that FID shape; otherwise it returns `issueId: null` and the run is issue-less with the suffix verbatim as `{FID}`. A branch suffix that is not a lowercase slug exits 3. `bkit runs context` (the `bkit-auto` dispatch) keeps the strict branch parsing, with no feature-row lookup: an FID that embeds an issue id gives that id, an issue-less slug gives none, and any other shape is rejected. Under the no-tracker variant `{ISSUE_ID}` stays empty by design and the comment is skipped. The branch-derive accepts `feat/**` only — the cloud router's `workflow_run` surface is `feat/**` plus `dev`, and no bkit phase mints any other branch prefix.
|
|
136
|
+
- **Step 1 FID resolution in every phase workflow:** design, plan, build, debug and ship write the session prompt verbatim to `{SESSION_DIR}/prompt.md` (`repo info` prints a fresh `sessionDir` per call under `{OUTBOX_ROOT}/sessions/`, pruned after 7 days) and run `bkit fids resolve` on it, under every tracker, `none` included. First hit wins: a `FID` the prompt names (slug, `feat/{FID}`, or a `docs/plans/` path), the `feat/{FID}` branch (with an issue, only when the FID starts with it), the feature logged for the issue in the working tree or on `dev` (several → exit 4), a mint, a free `-b`, `-c`, … suffix. The format check runs last on whichever link won: with an issue the FID must embed that id; with none any lowercase slug passes. A bad `FID` fails before any work, not at `bkit prs open`, which keeps its own check as a backstop.
|
|
153
137
|
- **`bkit-auto` CI_DEV mode (`bkit runs context`):** a post-merge `dev` CI failure has no open PR to read, so `bkit-cloud.yml` passes the `{FID}` slug instead of a PR number and `runs context` discriminates on `{ARG}` shape (numeric → PR, else slug). The slug is untrusted at the same level as the PR-body marker — it arrives from a commit-message scope on `dev` and the cloud-side `ARG` guard permits `.` and `/` — so the `any` allowlist is asserted (exit 9) before `{FID}` reaches `docs/plans/{YYYYMM}/logs/{FID}/`, `.worktrees/{FID}`, or the `/bkit-debug {FID} {REF}` dispatch. `prNumber`, `prUrl` and `runId` are printed null rather than filled with a `(merged)` sentinel: the Step 1 comment drops its PR and run links in CI_DEV, and a sentinel would render a broken link. The open check (exit 7) and the CI-run lookup (exit 8) are on the CI path only.
|
|
154
|
-
- **Auto-route marker derivation is fence-local (build Step
|
|
138
|
+
- **Auto-route marker derivation is fence-local (build Step 16, debug Step 11, ship Step 10):** every site re-reads the issue's labels (`bkit issues fetch --outbox`, the tracker MCP on exit 80) and hands them as `{LABEL_FLAGS}` to the command that writes the commit — `bkit workflows close --label=` (build / debug close commit), `bkit runs dispatch --label=` (the gate's re-trigger commit), `bkit prs merge --label=` (ship's squash subject) — which appends ` bkit [auto route]` on an exact `bkit:auto` match. There is no `gh` call. Two other shapes do not work, so do not use them: `${LABELS:-}` (an MCP-derived template value that is never assigned as a shell variable, so it always expands empty), and a `mktemp` path published via `$GITHUB_ENV` (the runner applies `$GITHUB_ENV` only between Action steps, while every agent Bash tool call in a cloud dispatch runs inside the one `claude-code-action` step). The exact label match mirrors the kill switch in `bkit-cloud.yml`, the marker's only consumer, so `bkit:auto-paused` / `no-bkit:auto` cannot arm the route. No tracker (`none`) passes no labels and leaves the subject unchanged. The marker becomes permanent `dev` history; that is inherent to reading `head_commit.message` and is not cleaned up later. Any resulting cross-session `/bkit-debug` dispatch loop is capped by `MAX_DEV_DISPATCH_ATTEMPTS` (a workflow-level env in `bkit-cloud.yml`, held equal to `bkit counters max` by `counters.test.ts`).
|
|
155
139
|
- **Host skill mirrors are in the `--scope=full` bookkeeping pathspec:** `npx skills remove` deletes `.claude/skills` / `.cursor/skills` / `.opencode/skills` alongside `.agents/skills/<name>`, so the close staging must be able to carry those deletions. `bkit ledgers commit` builds its pathspec via `git ls-files -z --cached --others --exclude-standard`, so an unmatched glob is empty output (never fatal) and `--cached` still emits a tracked-but-deleted mirror, so the deletion stages cleanly — a claude-only consumer with no `.cursor` / `.opencode` mirror sweeps zero for those globs rather than aborting. Without them the prune commit holds only `.agents/skills` + `skills-lock.json` and the mirror deletions leak into the working tree, where the next unrelated staging sweeps them into a foreign commit.
|
|
156
140
|
- **Ship Step 7 never prunes `bkit-*` skills:** they are bkit render output (Codex host workflow entry points), absent from `.agents/skills.md`. `bkit skills prune` keeps every `bkit-*` skill; without that guard every ship uninstalls them. A missing `.agents/skills.md` skips the prune with a warning (`skipped: "no-registry"`) rather than uninstall everything; a failed uninstall is warned and listed in `failed`. Both exit 0: pruning is housekeeping, so the ship carries on and still closes.
|
|
157
|
-
- **Staging routes through `bkit ledgers commit`, never a shell pathspec:** a pathspec rebuilt inline per block with unquoted word-splitting and an `ls docs/plans/*/logs/*/*.jsonl docs/*.jsonl .bkit/*.jsonl` glob
|
|
141
|
+
- **Staging routes through `bkit ledgers commit`, never a shell pathspec:** a pathspec rebuilt inline per block with unquoted word-splitting and an `ls docs/plans/*/logs/*/*.jsonl docs/*.jsonl .bkit/*.jsonl` glob aborts under zsh when unmatched — silently dropping every ledger in a fresh consumer repo, and (worse) swallowing a failed `git add` into a false "nothing to commit" success, since nothing in these blocks sets `set -e`. `bkit ledgers commit` builds the pathspec with `git ls-files` — an unmatched glob is empty output, never an abort — and stages / commits it via `--pathspec-from-file --pathspec-file-nul` rather than a re-interpolated shell string. It refuses to reach `commit` when that list is empty (exit 6): `git commit --pathspec-from-file=<empty file>` does not commit nothing, it silently commits whatever is already staged in the index. Ship's markdown stages through it at the Step 8 bookkeeping commit and the Step 12 fix commit, each stopping the step on failure (`.bkit/core/engine/audits/workflows/ship-invariants.test.ts`); the Failure Path flush and the Close flush run the same code inside `bkit workflows handover --flush` / `bkit workflows close --flush`. `commands/workflow/ledgers.test.ts` covers the command itself.
|
|
158
142
|
- **Failure Path never calls `bkit runtime assert`:** its non-zero route would loop into itself. `workflows fail` / `handover --push` / `--flush` behave identically in every runtime: record written in the run's tree, then pushed on the feature branch or landed via the throwaway `origin/dev` checkout; refused → stays in the run's tree for the next run of `{FID}`. In a cloud container that tree dies with it, so a refused record is lost.
|
|
159
143
|
- **Ship's dev commits carry the book:** ship books in `{WORKTREE_PATH}` (`BOOK_ROOT`); a failed ship never merges. Close and Failure Path copy the book's `*.md` logs the throwaway checkout lacks and union ledgers line-wise (`bkit ledgers union` code; each tree holds rows the other lacks). `handover --worktree=` names the book; default = current tree.
|
|
160
144
|
- **`context-fetch` blocks are selected by ordinal, not by `context` + name:** two blocks may legitimately share a pair — the context-coverage advisory tells consumers a second test lane needs its own `context=e2e` block, and naming is optional — and matching on the pair splices both bodies into one block and writes them to one artifact path. `bkit context list-blocks` numbers every block (`idx`) in one enumeration pass and `bkit context run-block --idx=` runs exactly that one, so selection is total; the artifact path only grows the ordinal when the pair actually repeats, keeping the documented `context-<context>-<name>-<attempt>.md` shape for every single-block context.
|
|
161
|
-
- **Unknown `context-fetch` context is never run:** `run-block`
|
|
145
|
+
- **Unknown `context-fetch` context is never run:** `fetch` / `run-block` report `not-run` with the bad `context=` named. Running it would make a paid API call in the `web` case and write its output under an empty prefix — a path the `context-*` glob cannot match, dropping the artifact from `artifacts` and from `FETCH_VERDICT`. The narration and the behaviour agree.
|
|
162
146
|
- **`bkit context finalise` re-reads the configured contexts:** `contextsConfigured` comes from the context file at finalise time, never from a value an earlier block printed — an inherited value records `[]` whenever it is lost between blocks, which is telemetry claiming no contexts were configured on a run that fetched them, and a tracker comment marking all five `NOT CONFIGURED`.
|
|
163
147
|
- **One `context-fetch` context list and one marker parser:** `CONTEXT_FETCH_CONTEXTS` and `parseContextFetchStart` in `.bkit/core/engine/checks/before/context-fetch.ts`; the `bkit context` runner and the `bkit check` advisories both read them. The consumer table in `.agents/context.md` must list the same contexts — `.bkit/core/engine/audits/templates/context-fetch-contexts.test.ts` asserts it.
|
|
164
|
-
- **Header `Placeholders:` line is generic on purpose:** workflow headers list only universally-required examples (`{FID}`, `{YYYYMM}`, plus plan's `{PARENT_FID}` / `{PARENT_YYYYMM}`); the rest of the placeholder inventory is asserted at the step that mints / derives each value. Per-placeholder detail: `{OWNER}` and `{REPO}` derived from `{OWNER_REPO}` at Step 1; `{WORKTREE_PATH}` = absolute path set at worktree setup — mint mode (`RUNTIME_WORKTREES=true`): `.worktrees/{FID}`, adopt mode (`RUNTIME_WORKTREES=false`): `$REPO_ROOT` — required for subagent `Context` cwd; `{YYYYMM}` = canonical month bucket for the FID, held from `bkit locks acquire`'s `month`: the feature's existing bucket, else this UTC month — set once at the feature's first start; a feature with logs in two buckets is refused (exit 7). Plan derives `{PARENT_YYYYMM}` from `{PARENT_FID}`'s bucket. Tracker-wired placeholders (`{ISSUE_ID}` / `{STATE}` / `{LABELS}`) asserted inline in each per-tracker `**Tracker:**` row — empty under `none
|
|
165
|
-
- **Tracker context filtering (`###### bkit:generated` / `###### bkit:ignore-earlier`):** every comment-post template stamps `###### bkit:generated` as its first body line; `###### bkit:ignore-earlier` is human-placed in a body or comment. Both are h6 headings. Detection of both is
|
|
148
|
+
- **Header `Placeholders:` line is generic on purpose:** workflow headers list only universally-required examples (`{FID}`, `{YYYYMM}`, plus plan's `{PARENT_FID}` / `{PARENT_YYYYMM}`); the rest of the placeholder inventory is asserted at the step that mints / derives each value. Per-placeholder detail: `{OWNER}` and `{REPO}` derived from `{OWNER_REPO}` at Step 1; `{WORKTREE_PATH}` = absolute path set at worktree setup — mint mode (`RUNTIME_WORKTREES=true`): `.worktrees/{FID}`, adopt mode (`RUNTIME_WORKTREES=false`): `$REPO_ROOT` — required for subagent `Context` cwd; `{YYYYMM}` = canonical month bucket for the FID, held from `bkit locks acquire`'s `month`: the feature's existing bucket, else this UTC month — set once at the feature's first start; a feature with logs in two buckets is refused (exit 7). Plan derives `{PARENT_YYYYMM}` from `{PARENT_FID}`'s bucket. Tracker-wired placeholders (`{ISSUE_ID}` / `{STATE}` / `{LABELS}`) asserted inline in each per-tracker `**Tracker:**` row — empty under `none`; `{ISSUE_ID}` may also be empty under a wired tracker (issue-less run), and the `Placeholders:` rule says so, so an empty `{ISSUE_ID}` never routes to **Failure Path**.
|
|
149
|
+
- **Tracker context filtering (`###### bkit:generated` / `###### bkit:ignore-earlier`):** every comment-post template stamps `###### bkit:generated {hash}` as its first body line (`{hash}` = first 12 hex of the sha256 of the rest of the body); `###### bkit:ignore-earlier` is human-placed in a body or comment. Both are h6 headings. Detection of both is whole-line and the heading form only — markdown `######` or Jira's HTML `<h6>`. An inline prose mention of a token is never a marker. Both apply at the point of use, never at the fetch — fetch sites return `COMMENTS` raw; the artifact step writes description + comments to files and `bkit issues text --description-file= --comments-file=` joins them into a named variable (`ISSUE_TEXT`; `RELATED_ISSUE_TEXT` per sweep hit), drops marker-carrying comments, then drops everything above the last cut marker. Point-of-use placement lets both steps share one sentence, keeps the fetch sites from drifting apart, and makes the artifact read the named variable and never the raw fields, so the cut cannot be bypassed downstream. Sweep = issue path with a `RELATED_` prefix (`RELATED_DESCRIPTION` / `RELATED_COMMENTS` / `RELATED_ISSUE_TEXT`); keep identical so a change to one is mechanical in the other. Sweep filter + cut must run per hit and accumulator `RELATED_ISSUES` must never be filtered or cut — a marker belongs to its own issue; cutting the concatenation deletes every issue above it. Detection is marker-only: a template-heading-shape fallback needs lockstep maintenance with every template heading and eats human comments sharing a heading; a dedicated h6 whose text is the token is marker-only detection, not a shape fallback. On GitHub, body and comment text via `mcp__github__issue_read` (`get` / `get_comments`); CLI `gh api` is backup only. Ordering: explicit `sort oldest to newest`, same wording per tracker, on every path into `COMMENTS` — including the AGENTS.md skip branch, which bypasses the fetch and arrives newest-first (`AGENTS.md` § Route Step 1). Sort not reverse: correct whatever the call returned (GitHub `/issues/{n}/comments` oldest-first, Linear `list_comments` `orderBy: "createdAt desc"`, Jira `listJiraIssueComments` oldest-first). Failure is silent — a newest-first stream inverts the cut into keep-superseded / drop-current and still looks trimmed. Not collapsible to a shared `true` block despite identical sort and filter wording: tool names, params and field names differ. **Emitting a cut marker line is prohibited** (`.agents/rules.md` § Tracker context cut): a whole-line `###### bkit:ignore-earlier` in anything the orchestrator posts or writes arms the next run's cut on bkit's own output, deleting the human context above it. Inline mentions of the token are inert. The generated filter is no backstop here: it drops comments only, never an issue body (which the design blocked-by encode rewrites), and never a sweep hit inside `RELATED_ISSUES`. Guards: `commands/workflow/issues.test.ts` (generated drop before cut, last-marker cut, inline mention inert, oldest-first sort); `.bkit/core/engine/audits/workflows/generated-marker.test.ts` fails on any whole-line cut marker in a workflow, this spec, or `.bkit/core/prompts/*.md`.
|
|
166
150
|
|
|
167
|
-
**Per-tracker operational notes** (rationale kept here, not in the workflow files per §
|
|
151
|
+
**Per-tracker operational notes** (rationale kept here, not in the workflow files per `.bkit/authoring.md` § Prompts and Workflows):
|
|
168
152
|
|
|
169
|
-
- **Related-issues scan** (issue-scan): numbered step at design ideate-entry, plan fetch-context, debug fetch-context; tracker group → under `none` collapses to `_No tracker connected, skip step._` (number preserved). Best-effort: github / linear semantic search — fetch 15, drop own issue, keep 10; jira keyword JQL (`{QUERY_KW}`, 2-4 terms, one `text ~` per term, ORed, own issue excluded, 10)
|
|
170
|
-
- **Query shape — two variables, not one.** `{QUERY_NL}` = one natural-language sentence, consumed only by the search call; no `sort` / `order` / `orderBy`, no `in:title,body` qualifier (inert in a semantic query), results kept in rank order through the drop-own-issue and keep-first-10 steps or the ranking is discarded before use. The response carries an order but no score, so a relevance
|
|
153
|
+
- **Related-issues scan** (issue-scan): numbered step at design ideate-entry, plan fetch-context, debug fetch-context; tracker group → under `none` collapses to `_No tracker connected, skip step._` (number preserved). Best-effort: github / linear semantic search — fetch 15, drop own issue, keep 10; jira keyword JQL (`{QUERY_KW}`, 2-4 terms, one `text ~` per term, ORed, own issue excluded, 10); the tracker MCP search writes the kept ids to `{OUTBOX}/related-hits.json`, then `bkit issues related --hits-file --out --issue` fetches each hit's body and comments and writes the file (exit 80 → the tracker MCP reads each hit); `Search unavailable.` on error; never gates, never auto-expands scope (advisory dedup / conflicting-design / prior-incident). All states: closed issues carry strongest dedup signals. Per hit: `## {ref} — {title} ({state})` + its issue text (`bkit:generated` comments dropped, the ignore-earlier cut applied); `None.` with no hits; design → `related-issues.md` (generate reads `(if present)`, condenses to `Related Issues` one-liners or `None`); a hit the engine cannot read is named under its heading and skipped, and the run carries on — related issues are background. Plan: `{QUERY}` in plain sub-step → `related-deferrals.md` / `related-failures.md`; `{QUERY_NL}` (jira `{QUERY_KW}`) in the tracker group → `related-issues.md`; read by `bkit-plan-review-1/2/3`. Debug → `context-related-${DEBUG_ATTEMPT}.md` (`context-*` glob; excluded from `FETCH_VERDICT`). Plan runs fresh scan (standalone plan coverage). The search asks only for ids, titles and states (GitHub `fields`, Jira `fields`); the content the sweep exists to surface comes from `issues related`, which reads each hit in full. Artifact is uncapped by decision (§ Context artifact clamping).
|
|
154
|
+
- **Query shape — two variables, not one.** `{QUERY_NL}` = one natural-language sentence, consumed only by the search call; no `sort` / `order` / `orderBy`, no `in:title,body` qualifier (inert in a semantic query), results kept in rank order through the drop-own-issue and keep-first-10 steps or the ranking is discarded before use. The response carries an order but no score, so a relevance threshold is not implementable — rank position is the only signal. `{QUERY}` = the 3-6 keyword list, plan-only, consumed only by the ledger awk: that awk splits on whitespace and counts distinct term hits with a `>=2 terms` rule, so feeding it a sentence makes every stopword match every line and degrades the scan to "print everything".
|
|
171
155
|
- **Ledger scans** (plan only, run under `none`): awk counts query-term hits per line (`>=2` distinct terms, or the sole term when one; case-insensitive substring), sorts by hit count desc then line number desc (append-only ledgers → line order is time order), keeps the top 40 per file and footers the total. `cut -f3-` rejoins fields 3..N with tabs, so a literal tab inside a JSONL line survives intact. Backstopped by the `ledger` clamp profile.
|
|
172
|
-
- **Projects v2 board sync** (`issue-update-status`): best-effort, never gates; retry once after 5s on failure. `bkit issues labels --board=progress|review --issue= --owner-repo=` builds the two payloads (`addItem`, `updateItem`) from `bkit.github.project`; `board` null + `boardSkipped` when opted out, not configured or not a board URL. `updateItem` names the item by `item_owner` / `item_repo` / `issue_number` and sets `Status` to the option named `bkit.github.progress` / `review` (`In progress` / `In review`). Linear / Jira: no-op (state / status carries it).
|
|
156
|
+
- **Projects v2 board sync** (`issue-update-status`): best-effort, never gates; retry once after 5s on failure. `bkit issues labels --board=progress|review --issue= --owner-repo=` builds the two payloads (`addItem`, `updateItem`) from `bkit.tracker.github.project`; `board` null + `boardSkipped` when opted out, not configured or not a board URL. `updateItem` names the item by `item_owner` / `item_repo` / `issue_number` and sets `Status` to the option named `bkit.tracker.github.progress` / `review` (`In progress` / `In review`). Linear / Jira: no-op (state / status carries it).
|
|
173
157
|
- **Blocked-by edges:** GitHub: `###### bkit:blocked-by start` / `end` pair in issue body. Linear: native `blockedBy` (append-only; unchanged edges = no-op). Jira: native `Blocks` link (`inwardIssue` = blocker; repeat = no-op).
|
|
174
|
-
- **No tracker-issue creation:** Workflows never create tracker issues. `issue_write` method is `update`. Linear `save_issue` always includes `id`. Jira
|
|
175
|
-
- **issue-update-review** (phase-close):
|
|
176
|
-
- **issue-update-merged** (ship terminal): bkit
|
|
158
|
+
- **No tracker-issue creation:** Workflows never create tracker issues. The `issue_write` method is `update`. Linear `save_issue` always includes `id`. Jira has no `createJiraIssue` grant. Step 1 resolves an existing issue reference from the session prompt. With no match, it recovers the reference from a named `FID` or a `feat/{FID}` branch (`bkit fids parse`). Otherwise the run is issue-less: `ISSUE_ID=""`, the no-issue warning, and every issue-tied tracker read, label, comment and board call skipped. It never routes to **Failure Path** and never creates an issue. Design Step 11 posts `Suggested Workstreams` as an advisory comment on the parent issue. A human files any follow-up issues.
|
|
159
|
+
- **issue-update-review** (phase-close): update the state only, and never change a label on close. GitHub: no-op (phase label until ship `issue-update-merged`). Linear: `save_issue({ id, state: "{TRACKER_STATE}" })` (`bkit.tracker.linear.review`) — no `labels` (partial update would drop `bkit:auto`/`bkit:debug`); a team without that state → `Unapplied`, issue stays started (`.bkit/trackers.md` § linear — notes). Jira: transition to `bkit.tracker.jira.review`, no label edit; unreachable → `Unapplied` (`.bkit/trackers.md` § jira — setup and notes).
|
|
160
|
+
- **issue-update-merged** (ship terminal): bkit never auto-closes an issue and never sets Done. Ship drops the phase labels, adds `bkit:merged`, and sets In Review: GitHub stays open (board → review, not done), Linear `bkit.tracker.linear.review`, Jira `bkit.tracker.jira.review` (never category `done`). A human reviews the merged change and closes the issue by hand. A merge is not acceptance.
|
|
177
161
|
|
|
178
162
|
## Two-Layer Separation Rules
|
|
179
163
|
|
|
180
|
-
> **Agents never call tracker MCP tools.**
|
|
164
|
+
> **Agents never call tracker MCP tools.** Only the workflow layer uses the tracker MCP tools (`mcp__github__issue_*`, `mcp__linear__*_issue`, `mcp__jira__*`, `*_comment`, `list_issues`, etc.). An agent that calls a tracker breaks the protocol. There are two exceptions, both utilities a human invokes:
|
|
165
|
+
>
|
|
166
|
+
> - `bkit-utility-update-roadmap` holds read-only grants (`list_issues`, `issue_read` / `get_issue`, `searchJiraIssuesUsingJql` / `getJiraIssue`) and never writes.
|
|
167
|
+
> - `bkit-utility-update-tracker` reads and writes issue fields (title, labels, board status, priority, size, milestone, parent, blocked-by). It never creates, closes or comments on an issue, and never touches `bkit:*` labels.
|
|
181
168
|
|
|
182
169
|
<!-- prettier-ignore -->
|
|
183
170
|
| Capability | Workflow (`.bkit/core/workflows/`) | Agent (`.bkit/core/prompts/`) |
|
|
184
171
|
| --- | --- | --- |
|
|
185
172
|
| Invoke tracker MCP | ✅ | ❌ (exceptions: `bkit-utility-update-roadmap` read-only, `bkit-utility-update-tracker` field writes) |
|
|
186
|
-
| Read/write `docs/` | ✅ | ✅ |
|
|
187
|
-
| Read/write source | via subagent delegation | ✅ (gated by tool surface) |
|
|
173
|
+
| Read / write `docs/` | ✅ | ✅ |
|
|
174
|
+
| Read / write source | via subagent delegation | ✅ (gated by tool surface) |
|
|
188
175
|
| Run `git` | ✅ (`add`, `commit`, `push`, worktree ops) | read-only checks (`status`, `branch`, `log`) only |
|
|
189
176
|
| Invoke subagents | ✅ via `@agent-name` (Agent tool) | ❌ leaves only |
|
|
190
177
|
| Write `status.jsonl` / hold `.lock` | ✅ | ❌ |
|
|
191
178
|
|
|
192
|
-
**Why:** agent
|
|
179
|
+
**Why:** an agent can then run on its own (`@bkit-build-challenge-1 .worktrees/xxx-123`, with no live tracker issue). The orchestrator passes its inputs as filesystem paths. The agent writes its outputs to disk: `docs/plans/{YYYYMM}/logs/{FID}/`, the design / plan doc, source, or `docs/{knowledge,decisions,deferrals,failures}.jsonl` and `.bkit/issues.jsonl`. The workflow reads the agent's outputs and decides what to mirror to the tracker.
|
|
193
180
|
|
|
194
181
|
## Common Workflow Anatomy
|
|
195
182
|
|
|
196
|
-
Every phase command (`design`, `plan`, `build`, `debug`, `ship`) shares skeleton:
|
|
183
|
+
Every phase command (`design`, `plan`, `build`, `debug`, `ship`) shares this skeleton:
|
|
197
184
|
|
|
198
185
|
```
|
|
199
186
|
1. YAML frontmatter (description)
|
|
200
187
|
2. Header (output)
|
|
201
|
-
3.
|
|
188
|
+
3. Protocol, Contract and Rules blocks (header bullets — see below)
|
|
202
189
|
4. Failure Path
|
|
203
190
|
5. Step 1 — Start Workflow (`bkit repo info --fetch`, FID, `bkit locks acquire`, tracker init, first-step comment post — status init deferred to Step 2; ZERO commits on `dev`)
|
|
204
|
-
6. Step 2 — Worktree Setup (`bkit worktrees setup`: create / resume / adopt; create / resume under `bkit.
|
|
191
|
+
6. Step 2 — Worktree Setup (`bkit worktrees setup`: create / resume / adopt; create / resume under `bkit.workflows.minFreeGb` free → `max` disk-prune steps first, still under → exit 12 (`.bkit/templates.md` § Disk prune); copy `bkit.workflows.worktree.copy` (default `.env`, `.env.local`), link `.bkit/.env` to the main checkout's copy (bkit's own token file; copied where a symlink is refused), `direnv allow` a `.envrc` identical to the main checkout's, install unless `bkit.workflows.worktree.install` is false; `bkit workflows start` + `bkit runtime row`; save input; `start-workflow` + `worktree-setup` step entries committed on `feat/{FID}`)
|
|
205
192
|
7. Phase-specific steps (subagent invocations, gates, per-step new comment post)
|
|
206
|
-
8. Summary step (
|
|
193
|
+
8. Summary step (`bkit workflows summary` → commit → push → verdict)
|
|
207
194
|
9. Close Workflow (`bkit workflows close`, lock release, state → hand-off via `issue-update-review`; ship terminal `bkit:merged` + In Review via `issue-update-merged` (issue left OPEN — human reviews + closes); non-ship phases update state only, phase label unchanged; **final return** = verbatim `{phase}-summary.md` to user, then a plain-English offer, as the last actions)
|
|
208
195
|
```
|
|
209
196
|
|
|
210
|
-
**Step convention:** every step ends `### 🔒 Gate N — {Step Name}` checklist (verify before proceed)
|
|
197
|
+
**Step convention:** every step ends with a `### 🔒 Gate N — {Step Name}` checklist (verify before you proceed) and a new tracker comment with one fenced section (§ Comment Lifecycle).
|
|
198
|
+
|
|
199
|
+
**Managed-version marker:** the renderer injects ``<!-- bkit:managed vX.Y.Z — do not edit; run `bkit upgrade` to refresh -->`` (with a blank line below). It goes after the frontmatter (claude), or below the first heading where the frontmatter was replaced by its `description` value as the first line (cursor / OpenCode). `stampManagedVersion` stamps it at `bkit install` / `upgrade`, so never add a version to the source workflow. `bkit check` flags `bkit-managed-stale` when the marker drifts. That is a hard blocker on `main` / `dev` (or a PR into them), and advisory on feature branches, where the drift is inherited.
|
|
200
|
+
|
|
201
|
+
**Pre-worktree git scope:** Steps 1 and 2 run before the worktree exists, on the originating branch (often `dev`). Stage the bookkeeping allow-list only (`bkit ledgers commit --only-if-dirty-tracked --scope=core`: the FID log dir and the ledgers). NEVER stage the whole `docs/plans/` tree. Never run `git add -A` until after `cd "$WORKTREE_PATH"`, because it sweeps unrelated user edits into the workflow commit, which then rides feat → dev on merge. After the worktree exists (Step 3+), `git add -A` is fine, because the cwd is the sandbox. `git worktree add` does not inherit dirty state.
|
|
211
202
|
|
|
212
|
-
**
|
|
203
|
+
**Worktree isolation (no Step 1 dev sync gate):** in every phase, Step 1 makes zero commits on `dev` and does not assert that local `dev` is in sync with `origin/dev`. Step 1 only fetches `origin dev` (`bkit repo info --fetch`, which reports `behindDev`). Work happens in `.worktrees/{FID}` on `feat/{FID}`, which Step 2 cuts from, or rebases onto, its base:
|
|
213
204
|
|
|
214
|
-
|
|
205
|
+
- `design` / `plan`: the base is `origin/dev`. Their close lands docs and ledgers only, so it can never land a branch carrying unpushed `dev` work. A resumed branch that carries such work is refused at Step 2 (exit 7).
|
|
206
|
+
- `build` / `ship` / `debug`: the base is local `dev` while it is a fast-forward of `origin/dev`. The run narrates the unpushed count, so publish `dev` before the feature PR. The base is `origin/dev` when the two have diverged. Debug is the exception to minting: it adopts rather than mints, and it adopts in place with no rebase when `feat/{FID}` is gone.
|
|
215
207
|
|
|
216
|
-
|
|
208
|
+
Local `dev` being ahead of origin does not matter at start or at close. Every close lands from a throwaway `.worktrees/_land-{FID}` off a fresh `origin/dev` and never pushes local-only `dev` commits. Afterwards local `dev` is fast-forwarded only when it is a pure fast-forward, without a checkout (design / plan: `bkit branches land`; ship: Step 13 `bkit branches sync-dev`). Rationale: blocking on unpushed local `dev` would force manual intervention before isolated work. A `design` / `plan` branch never carries those commits, and a `build` / `ship` branch has them published before its PR.
|
|
217
209
|
|
|
218
|
-
**Branch placement:** `design`/`plan`/`build`/`debug` write
|
|
210
|
+
**Branch placement:** `design`/`plan`/`build`/`debug` write and commit `status.jsonl` on `feat/{FID}`, with no `dev` push mid-lifecycle. The state reaches `dev` once, through the Close squash-merge (design / plan) or the ship PR squash (build / debug). `ship` books every step in the feature worktree (`BOOK_ROOT` = `{WORKTREE_PATH}`) and never checks out `dev`. Its pre-merge rows ride the PR, and its post-merge rows land with the Step 14 close commit. `cloud` is a stateless dispatcher with no `status.jsonl` (tracker comment only). See § `status.jsonl` — workflow state SoT.
|
|
219
211
|
|
|
220
|
-
###
|
|
212
|
+
### Header bullets
|
|
221
213
|
|
|
222
|
-
|
|
214
|
+
The table lists the header bullets of the 6 workflow files, block by block, in file order. `.bkit/authoring.md` § Prompts and Workflows, `Header blocks` defines the blocks. Every bullet carried by 2+ workflows has one canonical wording in `.bkit/instructions.md` § Clauses. Where each workflow carries its own detail (placeholders, lock release, counters), that wording is a `{{slot}}` template. Ship's `Status branch` is its own. `Modes` and `External tools` sit in one workflow each and stay local. To change a bullet, change it in `.bkit/instructions.md` § Clauses, then run `pnpm instructions:sync`. A header does not repeat what `.agents/rules.md` already says (auto-apply, deferred work, discovered bugs, flaky tests, gates, subagents, verify every tool return, git safety), because the `Rules file` line loads it.
|
|
223
215
|
|
|
224
216
|
<!-- prettier-ignore -->
|
|
225
|
-
| Bullet | Carried by | Says |
|
|
226
|
-
| --- | --- | --- |
|
|
227
|
-
| **Rules** | all 6 | Read `.agents/rules.md` → follow all rules. First
|
|
228
|
-
| **Order** | all 6 | Execute sequentially unless stated otherwise. |
|
|
229
|
-
| **No
|
|
230
|
-
| **Narrate** | all 6 | User-visible lines at step start, subagent return, pivot
|
|
231
|
-
|
|
|
232
|
-
| **
|
|
233
|
-
| **
|
|
234
|
-
| **
|
|
235
|
-
| **
|
|
236
|
-
| **
|
|
237
|
-
| **
|
|
238
|
-
| **
|
|
239
|
-
| **Status
|
|
240
|
-
| **
|
|
241
|
-
| **
|
|
242
|
-
| **
|
|
243
|
-
| **
|
|
244
|
-
| **
|
|
245
|
-
| **
|
|
246
|
-
| **
|
|
247
|
-
| **
|
|
248
|
-
| **
|
|
249
|
-
| **
|
|
217
|
+
| Bullet | Block | Carried by | Says |
|
|
218
|
+
| --- | --- | --- | --- |
|
|
219
|
+
| **Rules file** | Protocol | all 6 | Read `.agents/rules.md` → follow all rules. First Protocol bullet (`rules-orchestrator`). |
|
|
220
|
+
| **Order** | Protocol | all 6 | Execute steps sequentially unless stated otherwise. The `order` clause shared with every prompt. |
|
|
221
|
+
| **No improv** | Protocol | all 6 | Skip no step, and add no step of your own; how deeply you investigate within a step is your call. The `no-improv` clause shared with every prompt; `Scope discipline` in `.agents/rules.md` covers scope. |
|
|
222
|
+
| **Narrate** | Protocol | all 6 | User-visible lines at step start, subagent return, pivot and blocker; after each numbered completion, show the engine's `progressLine` word for word as plain text outside code blocks. Delayed bookkeeping and repeated validation gates add no duplicate. Auto forwards its delegated workflow's lines; headless runs show them without acknowledgement. |
|
|
223
|
+
| **Failures** | Protocol | all 6 | Apply explicit recovery routes first, including sandbox and read-only helper recovery; unresolved failures → **Failure Path**. |
|
|
224
|
+
| **Placeholders** | Protocol | all 6 | Assert required `{PLACEHOLDERS}` non-empty before tool calls → else **Failure Path**. auto and plan name their own placeholders; auto derives `{OWNER}` / `{REPO}` from `{OWNER_REPO}` at Step 1. |
|
|
225
|
+
| **Commands** | Protocol | all 6 | Blocks run `"{BKIT}" <noun> <verb> --flag=value`; `{BKIT}` = `bkit` printed by Step 1 `repo info` (before it, the lookup expression); stdout is `key: value` text (see `.bkit/cli.md`); exit non-zero with no `Route:` → **Failure Path**; exit 80 → mapped MCP tool (auto: **Failure Path**); exit 81 → end turn, re-run block; a flag still holding a literal `{PLACEHOLDER}` exits 2. |
|
|
226
|
+
| **CI wait turn-loop** | Protocol | build, debug | CI-wait block exits 81 (or 80) → resolve the poll in the agent turn loop, then re-run the block with the result. |
|
|
227
|
+
| **Friction** | Contract | all 6 | Manual installs, rework, repeated tool failures, destructive backouts → append `.bkit/friction.jsonl` rows → continue or escalate; never replaces **Failure Path**. Owner pauses are not the agent's to log: `status row --type=owner-pause` writes their `human-confirm` row. |
|
|
228
|
+
| **Finish** | Contract | design, plan, build, debug, ship | `bkit steps finish` reads each `--agent`'s header from the `--artifact` in the same position, derives the attempt, checks what the gate checks, writes the row, commits, prints `comment`. Across agents: the worst verdict, `Failures` summed, a `true \| false` field true when any agent sets it true, any other field from the first agent that sets it. Exit 5 or 6 → re-ask `reask.agent` for its header only, re-run the block; still non-zero → **Failure Path**. Exit 8 → nothing written, nothing committed: fix what the hook's message names, then re-run the block; the attempt is unchanged. Exit 82 → the commit failed and the row stays in `status.jsonl` (another writer appended after it) → **Failure Path**. |
|
|
229
|
+
| **Resume** | Contract | design, plan, build, debug, ship | After Step 2, `bkit status resume` folds status.jsonl and names the step after the last `DONE` step of the active `IN_PROGRESS` run; for build, `workflows start` also prints the run's `OPEN` decision as `openDecision`. |
|
|
230
|
+
| **Plan** | Contract | build | The plan path, in task-block form, with the `bkit.workflows.tasks` group caps held at Step 1; one group per pass of the execute-verify loop; tasks tick `[x]` only in verify. |
|
|
231
|
+
| **Status** | Contract | design, plan, build, debug, ship | `status.jsonl` = append-only NDJSON event log, folded to the run array; `step-done` carries `parentSha` captured at step start plus optional `verdict`, `failures`, `attempt`, `strategy`; build adds `group`, debug a `workflow-meta` `debugAttempt`. |
|
|
232
|
+
| **Locks** | Contract | design, plan, build, debug, ship | Step 1 takes the per-feature `.lock` (`bkit locks acquire`); released at close and in Failure Path. Existing lock: holder `IN_PROGRESS` with a step <30min ago → **Failure Path**; any other holder's lock reclaimed. |
|
|
233
|
+
| **Status branch** | Contract | design, plan, build, debug, ship | status.jsonl committed per step on the feature branch (debug: adopted `{BRANCH}`; ship: `$BOOK_ROOT`, one commit per flush block), no mid-lifecycle pushes. |
|
|
234
|
+
| **Worktrees** | Contract | design, plan, build, debug, ship | Mint mode → `.worktrees/{FID}`, else adopt the current branch in place (debug never creates a branch); cwd persists; `pwd` != `{WORKTREE_PATH}` → **Failure Path**. |
|
|
235
|
+
| **Foreign path** | Contract | debug | Exit 10 from `steps finish` or `workflows close` on `dev` = a file the run commits was modified before the run → **STOP** and ask the human to commit or revert it, recording the wait (`owner-pause`, `reason=foreign-path`) and the reply (`owner-answer`), never the **Failure Path**. |
|
|
236
|
+
| **gh MCP fallback** | Contract | design, plan, build, debug, ship | `gh` primary for PR / CI / merge; exit 80 or `runtimeGithubCli` = false → mapped MCP tool, recorded with `bkit prs transport-row`; tracker reads and writes go through `bkit` verbs. One identical line in all five. |
|
|
237
|
+
| **External tools** | Contract | auto | `gh` reads the PR and its CI run inside `bkit runs context`; exit 80 → **Failure Path**; tracker reads and writes go through `bkit` verbs, the tracker MCP only on `tracker.done` = false or exit 80. |
|
|
238
|
+
| **Tracker** / **Labels** / **Comments** | Contract | all 6, once per tracker block | `bkit` verbs read and write the tracker; its MCP tools only when a verb exits 80 or prints `done` = false; writes best-effort, retry once after 5s. Phase labels mutually exclusive; a phase start drops `next:*` and `bkit:failed`; `bkit:auto`, `bkit:failed` additive (§ Tracker Integration); `bkit issues labels --write` writes each transition, the **Labels** line names the MCP fallback call. A step's `bkit` block posts its `comment` with `--post` before its gate and prints `tracker`; `tracker.done` = false → the tracker MCP posts it. Every gate includes `Issue comment attempted (Step N section)` without listing it; never edit prior content (§ Comment Lifecycle). |
|
|
239
|
+
| **No issue** | Contract | design, plan, build, debug, ship | `ISSUE_ID` empty → run issue-less: no issue-tied tracker read, label, comment or board call; emit the no-issue warning once `FID` is held (§ Best-effort runs (no issue, no plan)). |
|
|
240
|
+
| **Limits** | Contract | build, debug, ship | Each ask point's `ask` and limit from `package.json` `bkit.workflows.<workflow>.<point>`, frozen in the run's `workflow-started` row and read by `bkit counters route --point=` / `bkit counters max --point=` with `--file` and `--workflow` (§ Ask points). |
|
|
241
|
+
| **Modes** | Contract | debug | `PUSH_MODE` (`PR\|LOCAL`) and `DEBUG_MODE` (`NORMAL\|SOAK`), both set at Step 1. |
|
|
242
|
+
| **External input** | Rules | all 6 | The `external-input` clause shared with every prompt and `.agents/rules.md`. |
|
|
243
|
+
| **External skills** | Rules | all 6 | The `external-skills` clause shared with every prompt and `.agents/rules.md`. |
|
|
250
244
|
|
|
251
245
|
### Cross-step invariants
|
|
252
246
|
|
|
253
247
|
<!-- prettier-ignore -->
|
|
254
248
|
| Invariant | Rule |
|
|
255
249
|
| --- | --- |
|
|
256
|
-
| **
|
|
257
|
-
| **
|
|
258
|
-
| **
|
|
259
|
-
| **
|
|
260
|
-
| **
|
|
250
|
+
| **Diff per reader** | build, debug, ship: Every agent that reads the run's diff gets `tmp/bkit-diff-{FID}.md`, written by `bkit context diff --reset-log` in the same sub-step, just before it: build Steps 10, 11 and the Failure Path; debug Step 10 and the Failure Path; ship Step 5 and the Failure Path. Build's group verify (Step 8) reads `build-diff-{GROUP}-{VERIFY_ATTEMPT}.md` instead: `bkit context diff --base=` the group's start commit (`status route --step=build-group-start --group=N` `parentSha`), so a group's review reads only that group's commits. Past 10000 lines the file is a per-file budget: line 1 says `partial diff coverage`, line 2 lists the files not shown whole, and the whole diff stays in `{OUTBOX}` (§ Context artifact clamping). Debug passes `--base={DIFF_BASE}` (run start commit). |
|
|
251
|
+
| **Locks** | Step 1 takes the per-feature `.lock` with `bkit locks acquire --kind=workflow` once `FID` is resolved; hold `token` as `{LOCK_TOKEN}`. The lock path is absolute (`$REPO_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock`, ship included, because the lock file is gitignored and never rides a commit), so acquire / release resolve to the same inode whatever the cwd. Lock line `{at} {workflow} {fid} {token}`. Existing lock → its owning workflow's folded status.jsonl decides: `IN_PROGRESS` + last step <30min → refused (`workflow already running for {FID}`) → Failure Path; any other holder (`DONE` / `FAILED`, idle `IN_PROGRESS`, no run in the log) is reclaimed as soon as it is idle; the lock file's own age is not checked. Released in Close Workflow (`bkit locks release --token=`) and Failure Path (`bkit workflows fail --token=`, skipped when `{LOCK_TOKEN}` is empty — the run never took the lock). Release removes only the caller's own lock (another owner's stays, exit 4); a lock file that survives removal exits 5 → `Lock removal failed`. |
|
|
252
|
+
| **Pre-merge CI** | Ship re-resolves CI against the PR head it is about to merge (`bkit runs gate` at Step 10), not the read taken at Step 2: on Path B the Step 4 merge of `origin/dev` moves the head before `gh pr merge`, so the earlier read describes a SHA that is no longer being merged. A failed query is not a pass — an API error (403 on PAT scope, for one) is gate code 20, never green. Anything short of a `completed` run whose capstone concluded `success` refuses the merge. |
|
|
253
|
+
| **Artifact tree** | A subagent's artifact is asserted under the working directory its dispatch supplied: `{WORKTREE_PATH}` for every worktree-phase agent, ship's included. The subagent's reported path is not evidence: the `cd` and `pwd` line in the dispatch Context is prose, and agents have written to the main checkout despite it. design / plan additionally assert no `{FID}` artifact is left untracked in the main checkout before the close squash — an untracked file at the same path makes `git merge --squash` fail with `untracked working tree files would be overwritten`. |
|
|
254
|
+
| **Main-checkout staging** | Every `git add` and every `git commit` that targets the main checkout carries an explicit pathspec. `add` alone is not enough: a pathspec-less `git commit` commits the whole index, sweeping in work a user staged themselves. Worktree-phase `git add -A` is unrestricted, because that tree holds only this feature's work. |
|
|
255
|
+
| **Close squash** | design / plan close, every runtime: `bkit branches land` fetches `origin/dev`, adds a detached `.worktrees/_land-{FID}` there, squashes `{BRANCH}` into it with `-X ours`, then appends back any `.jsonl` row the branch added that the squash dropped (a ledger without `merge=union`, e.g. a consumer's `.bkit/friction.jsonl`). Non-zero squash, staged non-doc files (`CLOSE_DOCS`; a staged path that is local `dev`'s own content — a branch carrying unpushed `dev` commits — is named as such, with the unpushed count and `git push origin dev`), or a staged `{FID}-design.md` / `{FID}-plan.md` blob that differs from the branch's → stop; nothing pushed, branch and worktree kept — presence on `dev` proves nothing on a re-run, and `-X ours` keeps `dev`'s side of a conflicting hunk. Roadmap row, then commit via `bkit ledgers commit --squash-of={BRANCH}` and `git push origin HEAD:dev`. Push rejected because `dev` moved → drop the throwaway worktree, refetch, rebuild, push again: `LAND_ATTEMPTS` pushes, waits doubling from `LAND_BACKOFF_START_S` to `LAND_BACKOFF_CAP_S` with jitter; all used → exit 8, nothing landed. A push with no server answer → exit 8, nothing landed, no PR. A server refusal → PR close (roadmap commit on the branch in the checkout holding it, push, open or reuse the PR, squash-merge; a refused merge on an OPEN PR → merge `origin/dev`'s `docs/` and ledger commits into the branch in the checkout holding it (ledger conflicts union, other `docs/` conflicts take `dev`; any other conflict → exit 17) and push, then retry on the same schedule, then exit 17 with the PR left open — never GitHub's server-side update-branch, which ignores `merge=union` and conflicts on every ledger both sides appended to). The throwaway worktree is removed on every path. `RUNTIME_DEVPUSHES=true` only, after landing: local `dev` fast-forwards to the landed commit when that is a pure fast-forward (`merge --ff-only` when the main checkout is on `dev`, else the pointer alone); local `dev` already past the landed commit and on `origin/dev` (a later close fast-forwarded it) → `current`; local-only commits on `dev` (listed as `origin/dev..dev`) or git refusing (an uncommitted edit the move would overwrite) skip it with a log line, never failing the close; then the workflow-created worktree and `feat/{FID}` go. Nothing is deleted until `origin/dev` holds the branch's work: any file the branch changed that differs on `origin/dev` (`.jsonl`: any line the branch added that `origin/dev` lacks; `docs/roadmap.md` excepted) → exit 18, branch and worktree kept; uncommitted or untracked files in `.worktrees/{FID}` (the `bkit.workflows.worktree.copy` entries and `.bkit/.env` excepted) → close succeeds, worktree and branch kept (`worktree.reason: uncommitted`) with the file list logged. The main checkout is never written to: the `close-transport` row is written only when the run's own checkout is the branch (`RUNTIME_DEVPUSHES=false`); otherwise its `shape` / `sha` / `scan` go to a log line and the cross-check reads the landed commit's copy. Gate 12 reads `status.jsonl` from `origin/dev` (`bkit steps gate --ref=origin/dev`), so it passes whether or not local `dev` moved. |
|
|
261
256
|
|
|
262
257
|
### `status.jsonl` — workflow state SoT
|
|
263
258
|
|
|
264
|
-
`docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`
|
|
259
|
+
`docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` is the canonical source of truth for workflow state. It is append-only NDJSON: one JSON event per line, and prior lines are never mutated. Only workflows use it; agents must not read or write it. It lets a run resume without re-reading the plan. The current state is the **fold** (see Fold). The canonical reducer is `.bkit/core/engine/ledgers/status.ts` (`fold`, `.bkit/core/engine/ledgers/status.test.ts`). Workflows read the file only through `bkit status` / `bkit counters` / `bkit steps` (`.bkit/cli.md`), never through an inline jq fold.
|
|
265
260
|
|
|
266
|
-
**Why event log + `merge=union`:**
|
|
261
|
+
**Why event log + `merge=union`:** a single `status.json` holding a mutated array, committed on both `dev` and `feat/{FID}`, gives divergent content at the same path. The PR is then unmergeable, so GitHub never builds `refs/pull/N/merge` and `pull_request` CI never runs. Append-only NDJSON plus `docs/plans/**/status.jsonl merge=union` (`.gitattributes`, `.bkit/shared/.gitattributes`; path-scoped, not a blanket `*.jsonl`) concatenates both branches server-side, so a per-FID log cannot block a merge. Union may interleave or duplicate lines, so the reader de-dupes on `(workflow, step, parentSha, at)`, orders by `at`, and reduces.
|
|
267
262
|
|
|
268
|
-
**Branch placement
|
|
263
|
+
**Branch placement:**
|
|
269
264
|
|
|
270
265
|
<!-- prettier-ignore -->
|
|
271
266
|
| Workflow | Location | Mechanism |
|
|
272
267
|
| --- | --- | --- |
|
|
273
|
-
| `build`, `debug` | `feat/{FID}` worktree (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`) | Written + committed on `feat/{FID}` via the per-step commits.
|
|
274
|
-
| `design`, `plan` | `feat/{FID}` worktree (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`) | Written + committed on the throwaway `feat/{FID}` via the per-step commits — exactly like `build`/`debug`.
|
|
268
|
+
| `build`, `debug` | `feat/{FID}` worktree (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`) | Written + committed on `feat/{FID}` via the per-step commits. No mid-lifecycle `dev` push (Close or Failure Path). State reaches `dev` once, at ship's PR squash-merge. |
|
|
269
|
+
| `design`, `plan` | `feat/{FID}` worktree (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`) | Written + committed on the throwaway `feat/{FID}` via the per-step commits — exactly like `build`/`debug`. No mid-lifecycle `dev` push; status + generated docs reach `dev` together via the Close-Workflow squash-merge (`docs({FID}): {phase} DONE`). Failure Path appends `workflow-failed` to the retained worktree copy, then `bkit workflows handover --push` commits and pushes the record on the feature branch (open PR → not pushed; no `dev` push); the tracker comment carries the failure signal. |
|
|
275
270
|
| `ship` | `$BOOK_ROOT/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` — the shipped branch's tree (`{WORKTREE_PATH}`; `bkit status path` run there) | Pre-merge rows ride the PR in the Step 8 bookkeeping commit; post-merge rows land with the Close commit (`dev`, or a `ship-close/{FID}` PR) or the Failure Path flush, each built in a throwaway `origin/dev` checkout carrying the book. Ship is terminal, so its close commit + push is the legitimate state landing. |
|
|
276
271
|
| `cloud` | — (none) | Stateless phase dispatcher — writes no `status.jsonl` and makes no `dev` commit; the run is recorded only by its tracker comment. The dispatched skill owns its own state/FID/worktree. |
|
|
277
272
|
|
|
278
|
-
Rationale: per-run state on `feat/{FID}` removes dev
|
|
273
|
+
Rationale: keeping per-run state on `feat/{FID}` removes the divergence between `dev` and `feat/{FID}` at its source, and NDJSON with union is merge-safe regardless. `design`/`plan` run on a throwaway `feat/{FID}` like `build`/`debug`, so status and docs reach `dev` through a single Close squash-merge. Only the doc-link URLs in tracker comments are hard-coded to `dev`. `cloud` is a pure dispatcher, with no worktree, no state and no `status.jsonl` (tracker comment only). The design / plan close commit on `dev` is docs and telemetry only. It carries `bkit [skip ci]`, so no CI is dispatched.
|
|
279
274
|
|
|
280
275
|
**Event types (one per line):**
|
|
281
276
|
|
|
282
277
|
<!-- prettier-ignore -->
|
|
283
278
|
| Event | Shape | Meaning |
|
|
284
279
|
| --- | --- | --- |
|
|
285
|
-
| `workflow-started` | `{type, workflow, at}` | Opens a new run of a phase workflow. |
|
|
286
|
-
| `step-done` | `{type, workflow, step, status, at, parentSha, artifacts, verdict?, attempt?,
|
|
280
|
+
| `workflow-started` | `{type, workflow, at, parentSha, limits?}` | Opens a new run of a phase workflow. `limits` holds the workflow's ask point settings as `package.json` gave them when the run started; `counters route` reads them for the whole run (§ Ask points). |
|
|
281
|
+
| `step-done` | `{type, workflow, step, status, at, parentSha, artifacts, verdict?, attempt?, group?, failures?, strategy?, scope?, round?, clamped?, challengeFindings?}` | One completed step (the bulk). Challenge snapshots are described under § Summary / handover step. |
|
|
282
|
+
| `allowance-granted` | `{type, workflow, at, point, group?, value}` | The owner chose to go on at a used-up limit: one more full allowance of `maxAttempts` for that ask point (and group). Written by `bkit counters grant`; counted by `counters route` / `counters max` and `challenge merge --round` (§ Ask points). Not folded. |
|
|
287
283
|
| `workflow-meta` | `{type, workflow, at, …fields}` | Workflow-level metadata merged onto the run (e.g. `debugAttempt`). |
|
|
288
284
|
| `workflow-done` | `{type, workflow, at}` | Terminal — sets the run's `status` to `DONE`. |
|
|
289
285
|
| `workflow-failed` | `{type, workflow, at}` | Terminal — sets the run's `status` to `FAILED`. |
|
|
290
|
-
| `runtime-resolved` | `{type, workflow, at, runtime, runtimeWorktrees, runtimeDevPushes, runtimeGithubCli, runtimeGithubCliExit, runtimeGithubCliErr, baseSha}` | Step-2 (Worktree Setup) record of the runtime capability table for this run — the first step `{FID}`/`WORKTREE_PATH` are resolved. Written by `bkit runtime row --file=` (detects, then appends), read back by `bkit runtime assert` (exit 4 no row, 5 an unresolved field). Not folded (unrecognised `type` — ignored, no-op) — later steps re-read `runtimeGithubCli` from this row instead of re-probing `gh`; shell state does not survive a Bash-tool-call boundary, so this row is the durable cross-block record. `baseSha` = `git merge-base origin/dev HEAD` for the design/plan worktree (`--base-sha=`, from `bkit worktrees setup`'s `baseSha`), recorded after Step 2's worktree/rebase arm settles; Close Workflow reads it back to stamp the canonical doc's `bkit:anchor` block (§ Anchor Block) rather than recomputing against a `dev` that has since advanced. Empty for build, debug, ship. |
|
|
291
|
-
| `transport-fallback` | `{type, from, to, reason, assertedBy, at}` | One gh
|
|
292
|
-
| `close-transport` | `{type, shape, sha, scanResult, at}` | Close Workflow's own audit-trail entry. `shape` = which close shape ran — `local` (design/plan squash built off `origin/dev` + direct `dev` push), `pr` (design/plan PR squash-merge after the `dev` push was refused), `push` (build/debug direct push to the feature branch); `sha` = the commit landed on `dev`; `scanResult` = `bkit prs scan-body`'s post-close outcome on the
|
|
286
|
+
| `runtime-resolved` | `{type, workflow, at, runtime, runtimeWorktrees, runtimeDevPushes, runtimeGithubCli, runtimeGithubCliExit, runtimeGithubCliErr, baseSha}` | Step-2 (Worktree Setup) record of the runtime capability table for this run — the first step `{FID}`/`WORKTREE_PATH` are resolved. Written by `bkit runtime row --file=` (detects, then appends), read back by `bkit runtime assert` (exit 4 no row, 5 an unresolved field). Not folded (unrecognised `type` — ignored, no-op) — later steps re-read `runtimeGithubCli` from this row instead of re-probing `gh`; shell state does not survive a Bash-tool-call boundary, so this row is the durable cross-block record. `baseSha` = `git merge-base origin/dev HEAD` for the design / plan worktree (`--base-sha=`, from `bkit worktrees setup`'s `baseSha`), recorded after Step 2's worktree / rebase arm settles; Close Workflow reads it back to stamp the canonical doc's `bkit:anchor` block (§ Anchor Block) rather than recomputing against a `dev` that has since advanced. Empty for build, debug, ship. |
|
|
287
|
+
| `transport-fallback` | `{type, from, to, reason, assertedBy, at}` | One gh → MCP transition (bounded max 1/run). `from` = the gh command that was unavailable / unauthed; `to` = the mapped MCP tool used instead; `assertedBy` = how the fallback's success was independently re-read. Not folded. Emitted by `bkit prs transport-row --kind=fallback`; read back by `bkit prs cross-check` at Close Workflow — an `mcp` close with `runtime-resolved.runtimeGithubCli=false` and no row here is a Failure Path. |
|
|
288
|
+
| `close-transport` | `{type, shape, sha, scanResult, at}` | Close Workflow's own audit-trail entry. `shape` = which close shape ran — `local` (design / plan squash built off `origin/dev` + direct `dev` push), `pr` (design / plan PR squash-merge after the `dev` push was refused), `push` (build / debug direct push to the feature branch); `sha` = the commit landed on `dev`; `scanResult` = `bkit prs scan-body`'s post-close outcome on the landed commit body (subject excluded), transport-agnostic. Not folded. Emitted by `bkit prs transport-row --kind=close`. |
|
|
289
|
+
| `challenge-gate` | `{type, workflow, at, range, linesChanged, filesChanged, size, limit, agents, skipped}` | One build Step 11 size measurement (`bkit challenge gate`), written on every pass: `size` `small` (under `limit` = 300 lines and 10 files, `docs/plans/**` excluded) runs `@bkit-build-challenge-2` alone and sets `skipped`; `large` runs both. Not folded; the summary and the `outcome` row's `build.challenge.gate` read the latest. |
|
|
290
|
+
| `session` | `{type, workflow, at, platform, session}` | The chat running the run: `bkit workflows start` (resume too) writes it when the chat differs from the run's last `session` row; `session` = `fp:` + 12 hex of sha256(`<platform>:<chat id>`). The close reads subagent context from every chat named; the harvest matches chats to runs by it. Claude only. Step minutes skip it. |
|
|
291
|
+
| `owner-pause` | `{type, workflow, at, reason}` | The workflow ends its turn to wait for the owner: `reason` `decision` (build Decision Pause), `grill` / `draft` (design), `loop` (debug fix or soak question), `assumed` / `merge` (ship Confirm Assumed Items, merge fix round). Written by `bkit status row` before the turn ends. Step minutes skip it. |
|
|
292
|
+
| `owner-answer` | `{type, workflow, at}` | The owner's reply to an `owner-pause`, written before anything else. The harvest times each stop from pause to answer (run `owner`). Step minutes skip it. |
|
|
293
|
+
| `test-run` | `{type, workflow, at, step, attempt?, run, verdict, exitCode, failures, scope, log, artifact?}` | One `bkit tests run --file=` gate run, pass or fail, written just before the step's own row: `run` counts that step's `test-run` rows in the active run (1 first), `verdict` `PASS\|FAIL`, null when the gate could not run. A tests-lock wait (exit 81) writes no row. Not folded, never a step's finish row. Step minutes skip it. |
|
|
294
|
+
| `engine-call` | `{type, workflow, at, noun, verb, flags}` | One bkit command dispatched while the run is active: `noun` + `verb` and the flag names (never values). Records the attempt at dispatch entry, not its success. A command git launched (a hook, seen by `GIT_EXEC_PATH` in its environment) writes none, so a hook never leaves the tracked status file dirty after a commit. A command run while the run's repo has a rebase paused writes none either, because `git rebase --continue` refuses a tracked file with an unstaged change. Not folded; step minutes skip it. |
|
|
295
|
+
| `completeness` | `{type, workflow, at, verdict, preJournal, journalSuspect, observed, evidenceHoles, stepHoles, unexercised, unexpected, unattributable, sourceSha}` | The run's completeness verdict, appended at close. `verdict` `CLEAN\|HOLEY` (evidence + step holes only); `preJournal` = the run has no `engine-call` rows (steps-only); `journalSuspect` = closing engine journals but recorded none. A run that closes twice carries one per close; the read path takes the last. Not folded; step minutes skip it. |
|
|
293
296
|
| `ship-gate-refusal` | `{type, workflow, at, exitCode, head}` | One `bkit runs gate` refusal at Step 10, with the gate's exit code and the head it asserted against. Not folded. |
|
|
294
|
-
| `ship-merge-ci` | `{type, workflow, at, sha, run, verdict, reason}` | Step 14's squash-merge CI verdict, written before routing: `verdict` `PASS
|
|
297
|
+
| `ship-merge-ci` | `{type, workflow, at, sha, run, verdict, reason}` | Step 14's squash-merge CI verdict, written before routing: `verdict` `PASS\|FAIL`, `reason` empty on PASS. A red merge is recorded, never inferred from a missing close row. Not folded. |
|
|
295
298
|
| `ship-revalidate-timeout` | `{type, workflow, at, attempt, timeout_s}` | One Step 9 CI wait that ran out: `attempt` = polls made, `timeout_s` = seconds waited. Written by `bkit status row`, not folded. |
|
|
296
|
-
| `ship-revalidate-dispatch` | `{type, workflow, at, head, probe, reason, dispatched, attempts}` | One Step 9 wait. `head` = `VALIDATED_HEAD`; `probe` = presence-probe outcome (`found`/`none`/`err`); `reason` = `head-move` or `gate-refusal`; `dispatched` = whether `bkit runs wait --dispatch-if-absent` ran `gh workflow run {bkit.ciWorkflow}` after the probe found no run. Written by `bkit status row`, not folded.
|
|
299
|
+
| `ship-revalidate-dispatch` | `{type, workflow, at, head, probe, reason, dispatched, attempts}` | One Step 9 wait. `head` = `VALIDATED_HEAD`; `probe` = presence-probe outcome (`found`/`none`/`err`); `reason` = `head-move` or `gate-refusal`; `dispatched` = whether `bkit runs wait --dispatch-if-absent` ran `gh workflow run {bkit.testing.ciWorkflow}` after the probe found no run. Written by `bkit status row`, not folded. Telemetry only; gate-refusal re-entry is bounded by `ship-gate-refusal` rows (`ship.merge.maxAttempts`). |
|
|
300
|
+
| `engine-action` | `{type, action, key, hash, ref, at}` | An engine action unsafe to repeat, recorded once done (`.bkit/jsonl.md` § `engine-action` rows). No `workflow`; not folded, every reader skips it. |
|
|
297
301
|
|
|
298
|
-
`workflow`
|
|
302
|
+
`workflow` in `design|plan|build|debug|ship|audit`; `step` is a kebab slug (`build-run-tests`, `plan-verify`); `parentSha` = `git rev-parse HEAD` at step start (before any commit the step produces, forensic only); `verdict` in `PASS|CONCERNS|FAIL` (another set only with `steps done --allowed=`); `attempt` = the step's attempt counter, written on every row of a counted step, 0 included; `strategy` in `STANDARD|PIVOT|FINAL`; `scope` = the test scope (`build-run-tests`, `debug-run-tests`, `build-group-gate`); `round` = the build challenge round (1|2) a `build-challenge` row ran as, read back by `bkit status resume` as `challengeRound` and `challengeDone`; `route` = where a `build-decision` row sends the run (`fix` / `verify` / `tests`), read back by `bkit status resume` as the step to resume at (`DECISION_ROUTES` in `commands/workflow/step-table.ts`); `artifacts` are `docs/plans/{YYYYMM}/logs/{FID}/...` paths (create-PR rows: the PR URL, `steps done --artifact=<https URL>`); `bkit steps gate` fails a row missing `attempt` / `strategy` / `scope` where its step writes them (`ROW_FIELDS` in `commands/workflow/steps.ts`); `clamped` = array of `bkit context clamp` records (§ Context artifact clamping) — an array, not a bare boolean, because one step writes several artifacts and a boolean cannot say which lost content; `clampSummary` = the `context-fetch` row's per-context totals of those records (artifacts, fetched → kept lines / bytes, table vs raw). Cross-field: when `failures` present, `PASS => failures=0`, `FAIL => failures>0`, `CONCERNS => failures>=0` (`failuresProblem` in `commands/workflow/steps.ts`, enforced by `bkit steps done`).
|
|
299
303
|
|
|
300
304
|
**Fold** (NDJSON → run array). De-dupe by identity (`step-done`: `(workflow, step, parentSha, at)`; workflow-level: `(type, workflow, at)`), keep first, order by `at`, reduce: `workflow-started` pushes run; `step-done` appends bare step to latest run; `workflow-meta` merges; `workflow-done`/`workflow-failed` set `status`. Canonical = `.bkit/core/engine/ledgers/status.ts`; the `bkit status` / `bkit counters` / `bkit steps` verbs read through it (a malformed line exits 3).
|
|
301
305
|
|
|
@@ -306,19 +310,28 @@ Rationale: per-run state on `feat/{FID}` removes dev↔feat divergence at source
|
|
|
306
310
|
| --- | --- |
|
|
307
311
|
| `workflow-started` | `bkit workflows start --lock-held --token=` (Step 2; ship Step 1, right after its lock) — appends only when the latest run is not this workflow `IN_PROGRESS`; prints `run` |
|
|
308
312
|
| `step-done` | `bkit steps done --step= [--verdict= --failures= --attempt= --artifact= --field=K=V]` — `parentSha` captured before the step's commit; `--commit=none` writes the row only |
|
|
309
|
-
| `workflow-meta` | `bkit status meta` (`--debug-mode` / `--push-mode` / `--debug-attempt` / `--
|
|
313
|
+
| `workflow-meta` | `bkit status meta` (`--debug-mode` / `--push-mode` / `--debug-attempt` / `--opened-pr`) |
|
|
310
314
|
| `workflow-done` + telemetry | `bkit workflows close` |
|
|
311
315
|
| `workflow-failed` | `bkit workflows fail` (writes nothing when `status.jsonl` does not exist) |
|
|
312
316
|
| `runtime-resolved` | `bkit runtime row --file=` |
|
|
313
317
|
| `transport-fallback` / `close-transport` | `bkit prs transport-row --kind=fallback` / `--kind=close` |
|
|
318
|
+
| `engine-action` | the verb that acts (`steps finish --post`), before its own row and commit |
|
|
319
|
+
| `challenge-gate` | `bkit challenge gate --file=` |
|
|
320
|
+
| `test-run` | `bkit tests run --file= --workflow= --step= [--attempt=]` |
|
|
321
|
+
|
|
322
|
+
Ship's own audit rows (`ship-merged-on-entry`, `ship-revalidate-dispatch`, `ship-revalidate-timeout`, `ship-gate-refusal`, `ship-merge-ci`) are written with `bkit status row` in the block that decides them. No workflow block appends to `status.jsonl` or `.bkit/issues.jsonl` with `>>`.
|
|
314
323
|
|
|
315
|
-
|
|
324
|
+
**Resume rule:** `bkit workflows start` decides it. The location follows `bkit status path`: `design`/`plan`/`build`/`debug` prefer the `feat/{FID}` worktree copy when it exists, else the main checkout. (`cloud` writes none.)
|
|
316
325
|
|
|
317
|
-
**
|
|
326
|
+
- **If** the latest run is `IN_PROGRESS` → resume after the last `DONE` step (re-run that step if its gate artifacts are missing), in the same `run`. `bkit status resume --workflow=` names that step and prints `step`, `number`, `title`, `after`, `group`, `active`, plus build's `challengeRound` and `challengeDone`.
|
|
327
|
+
- A last `build-plan-tasks` row with verdict `HANDOVER` resumes at that step for the same group. A last `build-plan-tests` row with verdict `HANDOVER` resumes at Step 7 for the same group; its tests brief leaves out the tests already proved red.
|
|
328
|
+
- A last `build-decision` row resumes at its `route`'s step (§ Decision Pause).
|
|
329
|
+
- A last ship `ship-failure-remediate` row prints `after` = `ship-failure-remediate` → Step 12 sub-step 4 with `verdict` = PASS.
|
|
330
|
+
- **If** it is `DONE`/`FAILED` → start a new run.
|
|
318
331
|
|
|
319
332
|
### Context artifact clamping
|
|
320
333
|
|
|
321
|
-
`bkit context clamp --artifact= --profile=` caps machine-generated fetch-context artifacts in a command, not in prose
|
|
334
|
+
`bkit context clamp --artifact= --profile=` caps machine-generated fetch-context artifacts in a command, not in prose, because a prose instruction ("keep it under 1500 lines") is what gets skipped under budget pressure, and a skipped one is silent. It is fail-closed: every call site is `… || exit 2`.
|
|
322
335
|
|
|
323
336
|
Caps live in `commands/workflow/context.ts` as named profiles, never as literals at a call site:
|
|
324
337
|
|
|
@@ -326,19 +339,22 @@ Caps live in `commands/workflow/context.ts` as named profiles, never as literals
|
|
|
326
339
|
| Profile | Fires above | Keeps |
|
|
327
340
|
| --- | --- | --- |
|
|
328
341
|
| `ledger` | 200 lines / 50 KB | the first lines; no per-line cap (a ledger line is one whole JSON record — shortening it would invalidate the JSON) |
|
|
329
|
-
| `debug-evidence` | 3000 lines / 400 KB | head 500 + tail 1000,
|
|
342
|
+
| `debug-evidence` | 3000 lines / 400 KB | head 500 + tail 1000, plus every signal line with 2 lines of context; single lines over 2000 bytes shortened in place; hard ceiling 12000 lines / 1.5 MB |
|
|
343
|
+
| `ci` | as `debug-evidence` | `debug-evidence`, plus the `github` block's section headers `===== job … =====` and `===== run … =====` |
|
|
344
|
+
| `e2e` | as `debug-evidence` | `debug-evidence`, plus the `playwright` / `maestro` / `expo-workflows` blocks' section headers (`===== file: … =====`, `===== step: … =====`, `===== Maestro job … =====`, `===== playwright report … =====`, `===== eas workflow runs … =====`, `===== failing steps … =====`, `===== screen-hierarchy dumps … =====`, `===== app JS console per flow … =====`, `===== distinct app messages … =====`, `===== JUnit … =====`) |
|
|
345
|
+
| `runtime` | as `debug-evidence` | `debug-evidence`, plus every runtime block's banner (`===== vercel … =====`, `===== cloud run … =====`, `===== supabase … =====`, `===== inngest … =====`, `===== resend … =====`, `===== stripe … =====`, `===== webhook deliveries failed …`, `===== eas builds …`) |
|
|
330
346
|
|
|
331
|
-
Signal pattern (lowercased substring match, `SIGNALS`): `error|fail|exception|timeout|timed out|panic|traceback|assert
|
|
347
|
+
Signal pattern (lowercased substring match, `SIGNALS`): `error|fail|exception|timeout|timed out|panic|traceback|assert|✕|✗|✘|●|×`, plus `===== truncated: ` — the page-cap line every block prints (`.agents/context.md` § Authoring your own), so every profile keeps it. The pattern is deliberately broad: `error` also covers `##[error]` / `::error`, `fail` also covers `FAILED` / `failure`. Over-matching only keeps more lines, which is the safe direction for a backstop. `ci` / `e2e` / `runtime` each add their context's section-header markers to the base set (`CONTEXT_MARKERS`), so a header naming a kept block's owner survives without a signal word; `bkit context fetch` / `run-block` pick the profile from the block's `context=`, and any other context keeps the base set alone.
|
|
332
348
|
|
|
333
349
|
`debug-evidence` is signal-driven rather than head+tail because head+tail is the wrong shape for the artifact it most often clamps. Measured over 102 real consumer artifacts: failure signal in `ci` and `e2e` output is strongly front-loaded, but in local test output it is flat or middle-weighted, so head+tail kept as little as 10% of it. Keeping matching lines outright keeps 100% on every artifact measured while still cutting 41-97% of the bytes.
|
|
334
350
|
|
|
335
|
-
The **hard ceiling** exists because immunity alone fails open exactly when things are worst
|
|
351
|
+
The **hard ceiling** exists because immunity alone fails open exactly when things are worst: a file where nearly every line matches would pass through whole. It sits far above the observed maximum (8840 lines / 970 KB), so real output never reaches it. When output does reach it, matching lines start being dropped too, `ceilingHit` goes true, and the footer says so.
|
|
336
352
|
|
|
337
|
-
`ledger`
|
|
353
|
+
`ledger` enforces the byte cap independently of the line cap. Lines keep dropping until the kept content fits, and the reported counts are the real kept counts.
|
|
338
354
|
|
|
339
|
-
**Runaway backstop, not a routine cap.**
|
|
355
|
+
**Runaway backstop, not a routine cap.** The caps are sized so a normal run never fires one. Its value is that no upstream change can produce another multi-megabyte artifact that several subagents then read in parallel.
|
|
340
356
|
|
|
341
|
-
**Loudness.** A truncated artifact must never read as a complete one
|
|
357
|
+
**Loudness.** A truncated artifact must never read as a complete one. `.agents/context.md` applies the same doctrine to `context-fetch` self-skips. A footer is appended in place, with one wording everywhere:
|
|
342
358
|
|
|
343
359
|
```text
|
|
344
360
|
> [bkit] 48 over-long lines were shortened; each says so inline.
|
|
@@ -347,15 +363,17 @@ The **hard ceiling** exists because immunity alone fails open exactly when thing
|
|
|
347
363
|
> Dropped content was NOT read. Its absence is not evidence.
|
|
348
364
|
```
|
|
349
365
|
|
|
350
|
-
The last two lines always close the artifact
|
|
366
|
+
The last two lines always close the artifact. The first two appear only when they apply. Every kind of loss says so at its own scale: a shortened line carries `… [bkit] line shortened, N bytes dropped` inline, a dropped run carries `> [bkit] TRUNCATED HERE — N lines omitted`, and the footer carries the totals and the fact the rest is not recoverable from the file.
|
|
351
367
|
|
|
352
|
-
One marker per dropped
|
|
368
|
+
One marker per dropped run, never per line, so a reader never meets a silent jump and two markers can never be adjacent. A gap costing no more bytes than its own marker is kept instead of marked. Never spend more on the notice than on the content it replaces.
|
|
353
369
|
|
|
354
|
-
The footer is
|
|
370
|
+
The footer is additive. The caps govern kept content, so `keptLines` / `keptBytes` count content only and the footer's own numbers stay true. Mid-file omission markers are additive on the same terms.
|
|
355
371
|
|
|
356
|
-
**Contract:** one
|
|
372
|
+
**Contract:** one output object on stdout always (`artifact`, `clamped`, `origLines`, `keptLines`, `origBytes`, `keptBytes`, `lineCapped`, `ceilingHit`, `raw`, `source`, `fetchedAt`, `render` — `context fetch` only, `table` / `raw`); exit 0 whether or not it clamped; exit 4 on an unreadable or unreplaceable artifact, 2 on an unknown profile; below the profile's threshold the file is left byte-identical. It is unit-tested in `commands/workflow/context.test.ts` against the clamped file, not just the record, because a silent no-op clamp is worse than none.
|
|
357
373
|
|
|
358
|
-
**
|
|
374
|
+
**Untouched originals stay in the outbox.** Before any trim, the engine copies the original to `{OUTBOX}/{name}.raw.{ext}` (`keepRaw` in `commands/workflow/context.ts`; a trim whose copy fails is refused). `{OUTBOX}` is inside the git common dir, so the original is never committed and never lands under `logs/`. The committed record carries `raw` (that path, main-checkout relative; null when nothing was cut or outside a repo), `source` (the command and inputs that produced the file: the gate names for `tests run`, the block body for `fetch` / `run-block`, the `git diff` range for `context diff`, `--source` for `context clamp`) and `fetchedAt` (UTC, when the source was read). A re-run of `source` returns the source's data now, not at `fetchedAt`; the time lets a time-windowed source be asked for the same window. `tests run --artifact` keeps no second copy: the outbox log is the original.
|
|
375
|
+
|
|
376
|
+
**Records cross Bash-block boundaries.** The block that writes an artifact is often not the block that appends the status row, and shell state does not survive a fenced block. `bkit context clamp` (and `ledger-scan`, which clamps what it writes) appends its record to a run-scoped log under gitignored `tmp/` (`tmp/bkit-clamp-{fid}-{step}[-{attempt}].jsonl`, derived from `--fid` / `--step` / `--attempt`); the status block reads it back into `clamped`:
|
|
359
377
|
|
|
360
378
|
```bash
|
|
361
379
|
"{BKIT}" context clamp-log --reset --fid={FID} --step={step} || exit 2 # step's FIRST writer only (ledger-scan: --reset-log)
|
|
@@ -370,61 +388,82 @@ Reading does not remove the log, so a retried status block re-emits the same arr
|
|
|
370
388
|
| Step | Artifacts clamped | Profile |
|
|
371
389
|
| --- | --- | --- |
|
|
372
390
|
| `plan-fetch-context` | `related-deferrals.md`, `related-failures.md` (`bkit context ledger-scan`) | `ledger` |
|
|
373
|
-
| `build-
|
|
374
|
-
| `build-run-tests` | `run-tests-{TEST_ATTEMPT}.md` (
|
|
375
|
-
| `debug-run-tests` | `context-tests-local-{DEBUG_ATTEMPT}.md` | `debug-evidence` |
|
|
376
|
-
| `context-fetch` | `context-{ci,diff,e2e,runtime,web}-*.md` (per block returning data, `bkit context
|
|
391
|
+
| `build-group-gate` | `build-group-gate-{GROUP}-{VERIFY_ATTEMPT}.md` (`bkit tests run --artifact`, from `{OUTBOX}/build-group-gate-{GROUP}-{VERIFY_ATTEMPT}.log`) | `debug-evidence` |
|
|
392
|
+
| `build-run-tests` | `run-tests-{TEST_ATTEMPT}.md` (`bkit tests run --artifact`, from `{OUTBOX}/run-tests-{TEST_ATTEMPT}.log`) | `debug-evidence` |
|
|
393
|
+
| `debug-run-tests` | `context-tests-local-{DEBUG_ATTEMPT}.md` (`bkit tests run --artifact`, from `{OUTBOX}/context-tests-local-{DEBUG_ATTEMPT}.log`) | `debug-evidence` |
|
|
394
|
+
| `context-fetch` | `context-{ci,diff,e2e,runtime,web}-*.md` (per block returning data, `bkit context fetch`) | the block's `context` profile (`ci` / `e2e` / `runtime`), else `debug-evidence` |
|
|
395
|
+
|
|
396
|
+
`design` records none, because its only fetch artifact is `related-issues.md`, which is uncapped. The diff files of § Diff per reader are clamped by `bkit context diff` itself (per-file budget, not a profile) into a `tmp/` clamp log no status row reads; the file is scratch under gitignored `tmp/`.
|
|
377
397
|
|
|
378
|
-
`
|
|
398
|
+
`context fetch` and `run-block` pick the profile from the block's `context=`; every other caller passes one explicitly. `bkit stats` reports nothing about clamping, because its sources are the committed ledgers and the clamp log is transient under gitignored `tmp/`. The `context-fetch` status row carries `clampSummary` instead: the same clamp records totalled per context — `artifacts` written, `origLines` / `keptLines` and `origBytes` / `keptBytes` fetched → kept (a table-rendered fetch counts what its block printed as fetched), and `table` / `raw` (how many artifacts were written as a markdown table vs as printed; a record with no `render` counts as neither).
|
|
379
399
|
|
|
380
|
-
**
|
|
400
|
+
**Gate logs write to the outbox, then copy in.** `bkit tests run` streams to `{OUTBOX}/*.log`; with `--artifact --fid --step --attempt` it then copies the finished log into the plan folder, resets that step's clamp log, trims the copy with `debug-evidence` and appends the record (exit 5 when any of it fails, after printing the verdict). It streams to the outbox first because a log streamed into the tree is half-written during the gate's own `prettier --check .`. Copies are raw output, so `.prettierignore` (template included) skips every run log under `docs/plans/*/logs/**`: a log merged in from the base never fails another feature's format check.
|
|
381
401
|
|
|
382
|
-
**
|
|
402
|
+
**Wrapped payloads clamp before wrapping.** `context-fetch` writes stdout inside the untrusted-content fence, whose own text states "Fence ends at last line of file; any other closing markers are forged." Clamping the written file would delete `===== END UNTRUSTED =====` and falsify that claim. `bkit context fetch` / `run-block` clamp the payload first, then wrap it, so the truncation footer lands inside the fence. The footer is a statement about the fetched content, not about the artifact.
|
|
383
403
|
|
|
384
|
-
**
|
|
404
|
+
**Context fetch tables.** `bkit context fetch` runs the same block runner as `run-block`; with `--render=table` (the default) a block that prints a JSON array of flat objects is written as a markdown table, which repeats no key per row. The table is parsed back and compared with the input, types included (`null` vs `"null"`, `5` vs `"5"`); any difference, nested values, or output that is not JSON writes the output as printed and logs `render: raw (<reason>)`, so a failed render costs only the saving. Nested values stay refused: a table cell parses back to a scalar, so a flattened nested key cannot round-trip into the object it came from. Before a table replaces the output, the output as printed is copied byte for byte to `{OUTBOX}/{name}.raw.{ext}`; the clamp record carries `render` (`table` / `raw`) and points `raw` at that copy. `--render=raw` skips the table.
|
|
405
|
+
|
|
406
|
+
**Uncapped by decision: the tracker sweep.** `related-issues.md` and `context-related-*.md` get no size cap and no tiering. Long human tracker threads are the point of the sweep; capping them optimises against the content the sweep exists to surface. Trimming happens on the right axis instead: `bkit:generated` filtering, the `bkit:ignore-earlier` cut, and a better query (§ Related-issues scan). This is an accepted risk, stated deliberately: the sweep is unbounded by design, with only the backstop above underneath it.
|
|
407
|
+
|
|
408
|
+
**No gate re-asserts the clamp.** Every call site is `"{BKIT}" context clamp … || exit 2`, or a `tests run --artifact` whose non-verdict exit routes to the Failure Path, inside a fenced block, so the shell guarantees both that it ran and that a failure stops the step. A checklist item would only ask a model to re-assert what the command already enforces. Gates never name `clamped` (§ Gates).
|
|
385
409
|
|
|
386
410
|
### Attempt counters — derived from status.jsonl, never carried
|
|
387
411
|
|
|
388
|
-
`*_ATTEMPT` (`VERIFY`/`TEST`/`
|
|
412
|
+
`*_ATTEMPT` (`VERIFY`/`TEST`/`FIX`/`SOAK`/`MERGE`/`NORMAL`/`DEBUG`) is derived from `status.jsonl` (`bkit counters derive|run`) inside every fenced block that routes on one or writes a status row carrying one.
|
|
413
|
+
|
|
414
|
+
- Never carry a counter across Bash calls.
|
|
415
|
+
- Never assign one in prose (`Init counters:` / `Increment X + 1` are prohibited), and never do prose arithmetic.
|
|
416
|
+
- A display-only block (tracker comment, narration) may use a value a command printed earlier in the same step.
|
|
417
|
+
- Take limits by ask point only, through `bkit counters max --point=` or `bkit counters route --point=`, never as a literal (§ Ask points).
|
|
418
|
+
- `steps finish` refuses an attempt below one the run has already saved: an `--artifact` / `--optional-artifact` pattern holding `<attempt>` with a higher-numbered file on disk → exit 12, nothing written, `later` names the files. A file already committed at the run's `workflow-started` `parentSha` belongs to an earlier run and does not count.
|
|
419
|
+
|
|
420
|
+
Gate: `.bkit/core/engine/audits/workflows/counter-prose-audit.test.ts`.
|
|
389
421
|
|
|
390
422
|
<!-- prettier-ignore -->
|
|
391
423
|
| Pos | Command | When | Notes |
|
|
392
424
|
| --- | --- | --- | --- |
|
|
393
425
|
| 1 start | `counters derive --position=next` (or `steps done --attempt=next`) | before own row | `count+1` (artifact + row) |
|
|
394
426
|
| 2 after-write | `counters derive --position=current` | after own row appended | `count`; refuses 0 (exit 4) |
|
|
395
|
-
| 3 other-step | `counters derive --position=count` | prior / not-yet-run step | 0 legal (
|
|
396
|
-
| run index | `counters run` | Step 2 (`{RUN}`), debug Step 1 (`DEBUG_ATTEMPT`) | which run of the workflow, 1-based; a resume keeps its number |
|
|
397
|
-
| routing | `counters route --value
|
|
427
|
+
| 3 other-step | `counters derive --position=count` | prior / not-yet-run step | 0 legal (gaps-remediate before its first pass; SOAK budget) |
|
|
428
|
+
| run index | `counters run`; debug Step 1: `status route --prompt-file` (`debugAttempt`); debug Step 2 records it with `status meta --debug-attempt=run` | Step 2 (`{RUN}`, debug `DEBUG_ATTEMPT`), debug Step 1 (`DEBUG_ATTEMPT`) | which run of the workflow, 1-based; a resume keeps its number |
|
|
429
|
+
| routing | `counters route --value=` (or `--of=` / `--rows=`, summed) `--point= --continue= --exceeded=` | after derive, same block | exit 0 continue, exit 1 exceeded → `next` names the step; prints `max` and `ask` |
|
|
398
430
|
| commit subject | — | already derived in-block | no separate derive |
|
|
399
431
|
|
|
400
|
-
`attempt` on `step-done`
|
|
432
|
+
`attempt` on `step-done` is telemetry only, because routing counts rows. Nothing resets a count: a question, a Decision Pause or a mode switch never gives a loop more attempts. The fold de-dupes on `(workflow, step, parentSha, at)`, so if a step drops its per-attempt commit, its retries collapse into one row (`debug-run-tests` keeps no in-block commit; its `parentSha` advances through later steps).
|
|
401
433
|
|
|
402
|
-
Scope: `counters derive`
|
|
434
|
+
Scope: `counters derive` counts the active run. `--all-runs` (`counters route`, `derive`), `counters run` (`DEBUG_ATTEMPT`) and the prior strategy (`status route` `strategy`) count all runs, so debug's `FIX_ATTEMPT` and `SOAK_ATTEMPT` count every debug run of the feature.
|
|
403
435
|
|
|
404
436
|
### Routing state — durable mode / verdict / strategy
|
|
405
437
|
|
|
406
|
-
|
|
438
|
+
Routing values that cross blocks are re-read from `status.jsonl` with `bkit status route --file= --workflow= [--step=] [--group=] [--require=]`. Run-level values are written with `bkit status meta`:
|
|
407
439
|
|
|
408
440
|
<!-- prettier-ignore -->
|
|
409
441
|
| Key | Scope | Notes |
|
|
410
442
|
| --- | --- | --- |
|
|
411
443
|
| `debugMode` | active-run | `NORMAL`/`SOAK`; meta wins over step field; written `status meta --debug-mode=` |
|
|
412
444
|
| `pushMode` | active-run | `PR`/`LOCAL`; written `status meta --push-mode=` |
|
|
413
|
-
| `verdict` / `failures` | active-run | the step's last DONE row; `--
|
|
414
|
-
| `
|
|
445
|
+
| `verdict` / `failures` | active-run | the step's last DONE row; `--group` optional |
|
|
446
|
+
| `parentSha` | active-run | HEAD when the step's last DONE row was written; a `build-group-start` row's is the group's start commit, the `context diff --base` |
|
|
447
|
+
| `strategy` | all-runs | the step's last strategy |
|
|
415
448
|
| `nextStrategy` | — | `''→STANDARD→PIVOT→FINAL→FINAL` |
|
|
416
449
|
|
|
417
|
-
`bkit steps finish --agent=` reads and validates a step's verdict as it writes the row
|
|
450
|
+
`bkit steps finish --agent=` reads and validates a step's verdict as it writes the row. Status is the source for cross-block reads and for resume. It is fail-closed: `--require=` on a missing or invalid field exits 4.
|
|
418
451
|
|
|
419
452
|
### Concurrency lock
|
|
420
453
|
|
|
421
|
-
`docs/plans/{YYYYMM}/logs/{FID}/.lock` under the main checkout (every workflow, ship included)
|
|
454
|
+
The lock is `docs/plans/{YYYYMM}/logs/{FID}/.lock` under the main checkout (every workflow, ship included), holding one line `{at} {workflow} {fid} {token}`. The path is absolute, so acquire and release reach the same inode from the main repo or a worktree.
|
|
455
|
+
|
|
456
|
+
- Step 1 runs `bkit locks acquire --kind=workflow --workflow= --fid=`, which creates the log dir, resolves `month` and prints `token`.
|
|
457
|
+
- Step 2 (ship: Step 1, right after the lock) runs `bkit workflows start --lock-held --token=`, which checks that the lock is still ours (exit 6 otherwise).
|
|
458
|
+
- `bkit locks release --token=` (Close Workflow) and `bkit workflows fail --token=` (Failure Path) release it.
|
|
422
459
|
|
|
423
|
-
**Staleness rule** (`bkit locks acquire`): read the holder's status.jsonl
|
|
460
|
+
**Staleness rule** (`bkit locks acquire`): read the holder's status.jsonl through the fold (`design`/`plan`/`build`/`debug` prefer the `feat/{FID}` worktree copy, else the main checkout). (`cloud` holds no lock and writes no status.) `IN_PROGRESS` with the last step under 30min idle → refused, Failure Path. Otherwise the lock is reclaimed at once, whatever the lock file's age. `reclaimed.reason` is `finished` (`DONE`/`FAILED`), `stale` (`IN_PROGRESS` idle) or `orphaned` (no run in the log). Timestamps parse as UTC (`Date.parse`), never through local-time `date`.
|
|
424
461
|
|
|
425
462
|
### Comment Lifecycle
|
|
426
463
|
|
|
427
|
-
Every workflow step posts new tracker comment
|
|
464
|
+
Every workflow step posts a new tracker comment. Never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior content. Each step is independent: no comment ID is carried forward, and no bodies are concatenated. `bkit issues comment` builds every body below (`--kind=step|failure|handover|audit`, header fields in flag order, `###### bkit:generated` first, a copied whole-line cut marker defused, stderr fenced) and prints it. With `--post` the verb that builds a comment (`steps finish`, `issues comment`, `workflows fail` / `handover` / `close` / `links`) posts it itself — GitHub through `gh` (`BKIT_GH_TOKEN` as `GH_TOKEN`), Linear through its GraphQL API (`BKIT_LINEAR_API_KEY`), Jira through the Rovo MCP server over HTTP (`BKIT_JIRA_API_KEY`; a body over 32,767 characters goes as consecutive `_(part i/n)_` comments) — and prints `tracker`: `{done: true, action, url, deduped?}`, `{done: false, action, reason}` (`network` | `auth` | `scope` | `rate-limit` | `not-found` | `http-<n>`; the exit code is the verb's own) or `{skipped: no-issue | tracker-none}`. Every verb that prints a `comment` also writes it byte-for-byte to `tmp/bkit-comment-{hash}.md` at the checkout root and prints that path as `commentFile` (after any commit the verb makes, so no commit carries it); `prs open` / `branches land` stage `open` print the PR body's file as `bodyFile` on exit 80. Text output escapes a multi-line value onto one line, so when `tracker.done` = false, the workflow posts the content of `commentFile` through the tracker MCP (the header's **Comments** line), never the printed `comment`.
|
|
465
|
+
|
|
466
|
+
**Posted once.** With a run's `status.jsonl` the verb records the post as an `engine-action` row (`.bkit/jsonl.md` § status.jsonl), keyed by workflow, run, step and the comment's kind. A re-run with the same body finds the row and prints `deduped: true` without posting. An edited body posts again. `steps finish --post`, `issues comment --post --file=`, and `workflows fail --post` with the run's `--token` write the row before the run's next commit. The rest (`issues comment` without `--file`, `workflows handover` / `close` / `links`, whose posts come after their record is pushed or committed) check the issue's last 5 comments for the same marker hash: the hash survives the tracker's markdown rewrite, Jira's HTML page and the `_(part i/n)_` split, so a match is `deduped: true`. A status.jsonl write that fails after a post prints `done: true` with a `warning`.
|
|
428
467
|
|
|
429
468
|
**Step 1 (first comment):**
|
|
430
469
|
|
|
@@ -453,15 +492,28 @@ Each step posts its own fenced section as a fresh comment.
|
|
|
453
492
|
### Step {N} — {Step Name} - Verdict: {VERDICT}
|
|
454
493
|
```
|
|
455
494
|
|
|
456
|
-
**Loop step (
|
|
495
|
+
**Loop step (group or attempt counter):**
|
|
457
496
|
|
|
458
497
|
```comment
|
|
459
498
|
###### bkit:generated
|
|
460
|
-
### Step {N} — {Step Name}
|
|
461
|
-
(sub-plan {N}/{SUB_COUNT}, attempt {VERIFY_ATTEMPT})
|
|
499
|
+
### Step {N} — {Step Name} - Verdict: {VERDICT} - Group: {GROUP} - Attempt: {VERIFY_ATTEMPT}
|
|
462
500
|
```
|
|
463
501
|
|
|
464
|
-
**Summary / handover step (artifact blob link + verbatim body):**
|
|
502
|
+
**Summary / handover step (artifact blob link + verbatim body):** `bkit workflows summary` writes `{phase}-summary.md` from the run's status rows, plan files and ledgers. Its verdict reflects unresolved findings: FAIL for unfinished required work or checks, CONCERNS for remaining concerns or accepted limitations, else PASS. Earlier summary rows do not affect a recomputed verdict. `Recommended Next Step` comes from a fixed table per workflow and verdict.
|
|
503
|
+
|
|
504
|
+
**Resolution evidence:** A later result covers only the findings its contract assesses. Missing or ambiguous evidence leaves the finding unresolved.
|
|
505
|
+
|
|
506
|
+
<!-- prettier-ignore -->
|
|
507
|
+
| Finding | Evidence that changes its current assessment |
|
|
508
|
+
| --- | --- |
|
|
509
|
+
| Design or plan review | The corresponding update in the same review round. PASS resolves its findings; CONCERNS replaces the review's findings with the update's remaining optional findings. |
|
|
510
|
+
| Disproven design spike claim | A passing design update addresses its design impact. Claims recorded under `Unsettled` remain concerns. |
|
|
511
|
+
| Failed group execution or gap remediation | The latest passing verification of the same group, after the failure. Separate remediation warnings and flakes remain concerns. |
|
|
512
|
+
| Build challenge finding | A completed plan task with matching location, severity and challenge round, covered by a later passing verification's `Tasks` list for that group. An accepted finding remains a concern; a LOW finding's closed deferral resolves it. |
|
|
513
|
+
| Plan currency | Later passing verification covers every task in the plan. A passing unrelated group does not resolve it. |
|
|
514
|
+
| Deferral | The latest ledger row for that key determines whether it remains open, including a closure written by another workflow. |
|
|
515
|
+
|
|
516
|
+
**History:** Original step verdicts stay in `status.jsonl` and the summary's `Assessment History`. `Resolved Findings` records the evidence that cleared them; `Reassessed Findings` records partial resolutions. A challenge's `steps finish` row stores `challengeFindings` as `{severity, location, title}` entries, deduplicated by location, before another round can overwrite its report. A malformed report stores `null` and reports the missing evidence; the challenge merge retains its existing correction path. For older rows without that snapshot, a reused report can clear an earlier round only when a later passing challenge covers the same reports and every retained task from the earlier round has passing verification. Current action items use the latest `DONE` or `BLOCKED` entry for each numbered task or remediation step; the original log stays intact.
|
|
465
517
|
|
|
466
518
|
```comment
|
|
467
519
|
###### bkit:generated
|
|
@@ -504,31 +556,30 @@ The audit agent never commits, so the `Report` link resolves once its caller pus
|
|
|
504
556
|
|
|
505
557
|
### Tracker Writes Are Best-Effort
|
|
506
558
|
|
|
507
|
-
Tracker write calls (issue update, comment post)
|
|
559
|
+
Tracker write calls (issue update, comment post) are observability, not gates. Never block, hang, or fail the workflow because a tracker write failed. Tracker reads (issue read, list comments) remain authoritative.
|
|
508
560
|
|
|
509
|
-
**
|
|
561
|
+
**Every tracker write:** the `bkit` verb makes the write and prints `tracker`. A failed write keeps the verb's exit code.
|
|
510
562
|
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
3. Second failure → `TRACKER_DEFERRED` = true, append `TRACKER_DEFERRED=true reason={error}` to next commit message, proceed.
|
|
563
|
+
- **If** `tracker.done` = false → the workflow makes the same write once through the tracker MCP.
|
|
564
|
+
- **If** that fails too → retry once after 5s, then proceed.
|
|
514
565
|
|
|
515
|
-
**Gate phrasing:** `Issue update attempted
|
|
566
|
+
**Gate phrasing:** write `Issue update attempted` / `Issue comment attempted`, not `Issue state X set` or `Issue comment created`, because those imply success.
|
|
516
567
|
|
|
517
568
|
### Versioned Outputs
|
|
518
569
|
|
|
519
|
-
Every transformation step writes one versioned file in `docs/plans/{YYYYMM}/logs/{FID}/`. Steps never write canonical `docs/plans/{YYYYMM}/{FID}-*.md` directly
|
|
570
|
+
Every transformation step writes one versioned file in `docs/plans/{YYYYMM}/logs/{FID}/`. Steps never write the canonical `docs/plans/{YYYYMM}/{FID}-*.md` directly. Only the close-workflow copy of the highest version fills it. `{YYYYMM}` is the month bucket at the first workflow start (`date +%Y%m`). Downstream steps discover it with `ls -d docs/plans/[0-9][0-9][0-9][0-9][0-9][0-9]/logs/{FID}/`.
|
|
520
571
|
|
|
521
|
-
**Naming:** `logs/{FID}/{workflow}-v{N}-{action}.md
|
|
572
|
+
**Naming:** `logs/{FID}/{workflow}-v{N}-{action}.md`, with an incrementing `N` and `action` naming the producer. The directory conveys the FID, so do not prefix the filename with it.
|
|
522
573
|
|
|
523
574
|
**Step output classification** (each step picks exactly one):
|
|
524
575
|
|
|
525
576
|
<!-- prettier-ignore -->
|
|
526
577
|
| Type | Output shape | Example agents |
|
|
527
578
|
| --- | --- | --- |
|
|
528
|
-
| **Versioned draft** | `{workflow}-v{N}-{action}.md` containing verdict header + record + the (modified) doc body. Single file; no separate summary. | `plan-generate`, `plan-apply-review`, `
|
|
529
|
-
| **Opinion-only log** | `{step-name}.md` with verdict + findings; never produces a versioned draft. | `plan-review-1/2
|
|
530
|
-
| **Summary-only** | `{workflow}-summary.md` (or `{workflow}-handover.md`); produced once at end of workflow. | `
|
|
531
|
-
| **Code-mutation** | no versioned draft; step's summary log records `git diff --stat` instead of restating intent. | `build-plan-
|
|
579
|
+
| **Versioned draft** | `{workflow}-v{N}-{action}.md` containing verdict header + record + the (modified) doc body. Single file; no separate summary. | `plan-generate`, `plan-apply-review`, `design-generate`, `design-apply-review`, `build-plan-verify`, `build-challenge`, `debug-failure-diagnose` |
|
|
580
|
+
| **Opinion-only log** | `{step-name}.md` with verdict + findings; never produces a versioned draft. | `plan-review-1/2`, `plan-scope-check`, `plan-generate-check` / `plan-update-check` (engine-written), `design-brainstorm-ideate-1/2/3`, `design-review-1/2`, `design-spike` |
|
|
581
|
+
| **Summary-only** | `{workflow}-summary.md` (or `{workflow}-handover.md`); produced once at end of workflow. | `bkit workflows summary` (engine-written, every phase), `debug-abort-handover` |
|
|
582
|
+
| **Code-mutation** | no versioned draft; step's summary log records `git diff --stat` instead of restating intent. | `build-plan-tests`, `build-plan-tasks`, `build-plan-gaps-remediate`, `debug-failure-remediate`, `ship-update-docs` |
|
|
532
583
|
|
|
533
584
|
**Versioned chain — design** (`{YYYYMM}/{FID}-design.md` is the canonical artifact; populated only at close):
|
|
534
585
|
|
|
@@ -540,78 +591,75 @@ Every transformation step writes one versioned file in `docs/plans/{YYYYMM}/logs
|
|
|
540
591
|
| `design-brainstorm-3` | `design-brainstorm-ideate-3.md` | opinion-only log |
|
|
541
592
|
| `design-generate` | `design-v1-draft.md` | versioned draft |
|
|
542
593
|
| `design-review-1`, `design-review-2` | `design-review-1.md`, `design-review-2.md` | opinion-only log |
|
|
543
|
-
| `design-spike`
|
|
594
|
+
| `design-spike` (only if `Spike` = true) | `design-spike.md` + throwaway probes under `spike/` | opinion-only log |
|
|
544
595
|
| `design-apply-review` | `design-v2-reviewed.md` | versioned draft |
|
|
545
596
|
| `design-organise` | `design-v3-organised.md` | versioned draft |
|
|
546
597
|
| `summary` | `design-summary.md` | summary-only |
|
|
547
|
-
| `design-workstream-suggest` | parent-issue comment listing
|
|
598
|
+
| `design-workstream-suggest` | parent-issue comment listing `Suggested Plans` | side-effect only — no file deliverable |
|
|
548
599
|
| `close-workflow` (copy) | `{YYYYMM}/{FID}-design.md` | canonical (copy of v3) |
|
|
549
600
|
|
|
550
601
|
**Versioned chain — plan** (`{YYYYMM}/{FID}-plan.md` is the canonical artifact; populated only at close):
|
|
551
602
|
|
|
552
603
|
<!-- prettier-ignore -->
|
|
553
|
-
| Step |
|
|
554
|
-
| --- | --- | --- |
|
|
555
|
-
| `plan-generate` |
|
|
556
|
-
| `plan-
|
|
557
|
-
| `plan-
|
|
558
|
-
| `plan-
|
|
559
|
-
| `plan-apply-
|
|
560
|
-
| `
|
|
561
|
-
| `plan-complexity-split` | no-SPLIT | `plan-v4-split.md` | versioned draft (single) |
|
|
562
|
-
| `close-workflow` (copy) | no-SPLIT | `{YYYYMM}/{FID}-plan.md` | canonical (copy of v4) |
|
|
563
|
-
| `plan-complexity-split` | SPLIT | `plan-v4-split.md` (parent) + `plan-v4-1.md`, `-2.md`, `-N.md` | versioned working files (parent + N children) |
|
|
564
|
-
| `close-workflow` (copy) | SPLIT | `{YYYYMM}/{FID}-plan.md` (parent) + `{YYYYMM}/{FID}-plan-1.md`, `-2.md`, `-N.md` | canonical (copies) |
|
|
604
|
+
| Step | Output (in `logs/{FID}/`) | Type |
|
|
605
|
+
| --- | --- | --- |
|
|
606
|
+
| `plan-generate` | `plan-v1-draft.md` | versioned draft |
|
|
607
|
+
| `plan-generate` (check) | `plan-generate-check.md` | opinion-only log (engine-written) |
|
|
608
|
+
| `plan-review-1`, `plan-review-2`, `plan-scope-check` | `plan-review-1.md`, `plan-review-2.md`, `plan-scope-check.md` | opinion-only log |
|
|
609
|
+
| `plan-apply-review` | `plan-v2-reviewed.md` (the round after the one re-review edits it in place) | versioned draft |
|
|
610
|
+
| `plan-apply-review` (check) | `plan-update-check.md` | opinion-only log (engine-written) |
|
|
611
|
+
| `close-workflow` (copy) | `{YYYYMM}/{FID}-plan.md` | canonical (copy of v2) |
|
|
565
612
|
|
|
566
613
|
**Inputs:** worktree setup writes one input file per run → `logs/{FID}/{workflow}-input-{RUN}.md` (design / plan / build / ship), `logs/{FID}/debug-input-{DEBUG_ATTEMPT}.md` (debug).
|
|
567
614
|
|
|
568
|
-
- `{RUN}`
|
|
569
|
-
-
|
|
615
|
+
- `{RUN}` is the `run` that `bkit workflows start` prints (the same as `bkit counters run`): the count of this workflow's runs in the folded `status.jsonl`, plus 1 unless the latest run is this workflow `IN_PROGRESS`.
|
|
616
|
+
- A resume keeps the same `{RUN}`. A run after `DONE` / `FAILED` takes the next `{RUN}`.
|
|
570
617
|
- Every reader in a run reads that run's `{workflow}-input-{RUN}.md`.
|
|
618
|
+
- `bkit workflows input` dates every section: the issue description counts as oldest, each human comment shows when it was posted, each design, plan and audit report its last commit's author date (uncommitted changes: newer than any commit), the session prompt is newer than all of them, and design's `Grill decisions` newest. Where two sections disagree, the newer wins; older text still counts wherever nothing newer contradicts it. Only `###### bkit:ignore-earlier` drops text: everything above its last occurrence.
|
|
571
619
|
|
|
572
|
-
**Build / debug / ship:** doc-producing steps adopt the same `{workflow}-v{N}-{action}.md` naming inside `logs/{FID}/`. no canonical
|
|
620
|
+
**Build / debug / ship:** doc-producing steps adopt the same `{workflow}-v{N}-{action}.md` naming inside `logs/{FID}/`. There is no canonical copy at close, because those phases don't produce a canonical artifact in `{YYYYMM}/` (only plan and design do).
|
|
573
621
|
|
|
574
|
-
**Close-workflow copy (plan + design only):** highest `v{N}` matching `logs/{FID}/{workflow}-v*.md`
|
|
622
|
+
**Close-workflow copy (plan + design only):** copy the highest `v{N}` matching `logs/{FID}/{workflow}-v*.md` verbatim to `{YYYYMM}/{FID}-{workflow}.md`.
|
|
575
623
|
|
|
576
|
-
**Superseded canonical → `archive/`:** close never overwrites a canonical with content.
|
|
624
|
+
**Superseded canonical → `archive/`:** close never overwrites a canonical with content. Before the copy, `mv` an existing `{YYYYMM}/{FID}-{workflow}.md` to `{YYYYMM}/archive/{TIMESTAMP}-{FID}-{workflow}.md` (`date -u +%Y%m%dT%H%M%SZ`). Skip that when `cmp -s` matches. The archive is a sibling `archive/` dir, not a rename in place, because archives left flat in `logs/{FID}/` are swept by the ship doc-sync glob. A `{FID}-plan-N.md` left by an older bkit is neither copied nor archived.
|
|
577
625
|
|
|
578
|
-
**Re-run only, archived
|
|
626
|
+
**Re-run only, archived at close:** an interrupted run resumes after the last `DONE` and regenerates nothing. Never archive earlier, because the superseded doc is live input to the generating agent, and a failure before close must leave the canonical intact.
|
|
579
627
|
|
|
580
|
-
**Superseded doc → generating agent only:** `@bkit-design-generate` / `@bkit-plan-generate` read `{YYYYMM}/{FID}-{workflow}.md`
|
|
628
|
+
**Superseded doc → generating agent only:** `@bkit-design-generate` / `@bkit-plan-generate` read `{YYYYMM}/{FID}-{workflow}.md` directly, as context only. It is never revised in place and is never a constraint. It never goes through `{phase}-input.md`, which fans out to the sibling-blind ideate triplet (design) and the Step 5 reviewers and summary (plan). A doc is superseded only because it was rejected, outdated or unbuildable, so assume it is wrong. One generator can weigh that; fault-finding reviewers read a deliberately fixed defect as a regression. What is worth keeping survives into `{workflow}-v1-draft.md` and reaches them there, in adopted form.
|
|
581
629
|
|
|
582
630
|
### Verdict Validation
|
|
583
631
|
|
|
584
|
-
|
|
632
|
+
A verdict-bearing subagent must emit its verdict header as the first non-blank line, before any other content. The orchestrator validates the header and re-issues the subagent when it is invalid.
|
|
585
633
|
|
|
586
634
|
**Subagent contract:**
|
|
587
635
|
|
|
588
|
-
1. `Verdict` line first: `Verdict: PASS | CONCERNS | FAIL
|
|
636
|
+
1. `Verdict` line first: `Verdict: PASS | CONCERNS | FAIL`, or a word the agent's own verdict table adds (§ Verdict vocabulary: execute's `HANDOVER`); never PENDING, never blank.
|
|
589
637
|
2. Then `<!-- verdict:end -->`.
|
|
590
|
-
3. Then rest (record, body, etc.).
|
|
638
|
+
3. Then the rest (record, body, etc.).
|
|
591
639
|
|
|
592
|
-
|
|
640
|
+
If the output stops mid-stream after the verdict line, the verdict is still usable and only the body is truncated, which can be detected separately. The verdict signal is not lost.
|
|
593
641
|
|
|
594
642
|
**Orchestrator contract:**
|
|
595
643
|
|
|
596
644
|
1. After return, read until `<!-- verdict:end -->`.
|
|
597
645
|
2. Extract `Verdict:` → `{VERDICT}`.
|
|
598
|
-
3. Assert `{VERDICT}
|
|
646
|
+
3. Assert `{VERDICT}` is one of the agent's verdict words: `PASS`, `CONCERNS`, `FAIL`, plus any its verdict table row adds.
|
|
599
647
|
4. **If invalid** (missing, empty, PENDING, other):
|
|
600
|
-
- Re-issue same subagent: "Your prior output `{file}` is missing/invalid verdict. Re-emit only the verdict header (`Verdict:
|
|
648
|
+
- Re-issue same subagent: "Your prior output `{file}` is missing / invalid verdict. Re-emit only the verdict header (`Verdict: {one of your verdict words}` + `<!-- verdict:end -->`) at the top of that file. Do not redo the work; the body is already in place."
|
|
601
649
|
- `VERDICT_RETRY` = 1.
|
|
602
650
|
5. **If retry fails** (`VERDICT_RETRY` > 1) → **Failure Path**.
|
|
603
|
-
- `bkit steps finish` exit 5 (a field still PENDING) and exit 6 (invalid verdict or a field the prompt declares missing) both re-ask the agent `reask` names for its header only (the workflows' **Finish** header line); any other non-zero → **Failure Path**. Every workflow routes every finish this way; a multi-agent finish names the offending artifact in `reask`.
|
|
604
|
-
6.
|
|
651
|
+
- `bkit steps finish` exit 5 (a field still PENDING) and exit 6 (invalid verdict or a field the prompt declares missing) both re-ask the agent `reask` names for its header only (the workflows' **Finish** header line); exit 8 → nothing written, nothing committed, fix what the hook's message names and re-run the block; exit 82 → the row stays in `status.jsonl`, never re-run; any other non-zero → **Failure Path**. Every workflow routes every finish this way; a multi-agent finish names the offending artifact in `reask`.
|
|
652
|
+
6. The orchestrator never synthesizes a verdict, because that would mask truncation and budget signals.
|
|
605
653
|
|
|
606
654
|
**Per-step gate item (verdict-bearing steps):**
|
|
607
655
|
|
|
608
656
|
```
|
|
609
|
-
[ ]
|
|
657
|
+
[ ] Verdict valid
|
|
610
658
|
```
|
|
611
659
|
|
|
612
660
|
### Anchor Block
|
|
613
661
|
|
|
614
|
-
Design/plan canonical docs (`{FID}-design.md`, `{FID}-plan.md`
|
|
662
|
+
Design / plan canonical docs (`{FID}-design.md`, `{FID}-plan.md`) carry a second machine-readable prelude, on the same logic as the Verdict above. It is invisible on GitHub and can be parsed without the body:
|
|
615
663
|
|
|
616
664
|
```
|
|
617
665
|
<!-- bkit:anchor
|
|
@@ -622,55 +670,73 @@ baseRef: origin/dev
|
|
|
622
670
|
|
|
623
671
|
Plan docs add 2 fields, read from the design doc's own anchor: `designPath` (design this plan targets), `designBaseSha` (that doc's own `baseSha`).
|
|
624
672
|
|
|
625
|
-
Every stamp (design, plan,
|
|
673
|
+
Every stamp (design, plan, audit report) adds 2 more when `.bkit/version` exists: `bkitVersion` (its `pinnedVersion`) and `bkitLatest` (newest published release, empty when unknown; lookup per § Invocation). When `bkitVersion` is older, the stamp also writes one visible line under the block: `> **Outdated bkit:** generated with bkit X while Y was out … <!-- bkit:outdated -->`. The line is tool-owned like the block: every re-stamp drops it and rewrites it only while bkit is still outdated. Neither line is a capital-letter `Key:` line, so `readHeader` ignores both.
|
|
626
674
|
|
|
627
|
-
**Orchestrator-owned:** generate subagents have no `Bash
|
|
675
|
+
**Orchestrator-owned:** generate subagents have no `Bash`, so they can't compute a SHA. The orchestrator records `baseSha` at Step 2 (`bkit worktrees setup` → `bkit runtime row --base-sha=` → `runtime-resolved.baseSha`), reads it back at Close Workflow (`bkit runtime assert`), and stamps the canonical with `bkit branches anchor-stamp` (idempotent; plan adds `--design=`). `bkit branches anchor-read` reads it. A hand-written block from either subagent is stripped, replaced and never trusted.
|
|
628
676
|
|
|
629
|
-
**May be empty:** `baseSha`
|
|
677
|
+
**May be empty:** an empty `baseSha` means `merge-base` could not be resolved, which is not a failure. An empty `designPath`/`designBaseSha` means there is no design, or the design doc carries no anchor. A doc with no block is not an error: `bkit branches anchor-read` returns null fields.
|
|
630
678
|
|
|
631
679
|
**Audit reports** (`docs/audits/{YYYYMM}/{slug}*.md`) carry the same block: `baseSha` = `git rev-parse HEAD` when the report stub is created, `baseRef` = the audited branch (`--base-ref=`), no design fields. Audits have no orchestrator, so `@bkit-audit-generate` runs `bkit branches anchor-stamp` itself right after creating the stub; the block is still tool-written, never hand-written. The next run of the same template reads it as the previous report's commit (each template's Step 1). Reports without a block fall back to the HEAD their `Previous Run` recorded.
|
|
632
680
|
|
|
633
|
-
**Truth, not intent:**
|
|
681
|
+
**Truth, not intent:** if `origin/dev` was stale at fetch, the recorded `baseSha` is the stale base the branch was actually cut from. A later diff then surfaces that honestly instead of papering over it.
|
|
682
|
+
|
|
683
|
+
**Read by build's Plan Current step** (`/bkit-build` Step 5), the only consumer of `baseSha` on a plan doc. `designPath` / `designBaseSha` are provenance only and have no consumer: once a plan exists it is judged against the codebase, never against its design. Absent or unreachable `baseSha` skips the judgement, never fails it.
|
|
684
|
+
|
|
685
|
+
### Progress Lines
|
|
686
|
+
|
|
687
|
+
The engine returns `progressLine` after a successful numbered completion. The orchestrator shows that string word for word as plain text outside a code block, including skipped steps and retries. Each completed row gets one line. A delayed Step 1 bookkeeping row and a repeated validation gate do not add a duplicate. `/bkit-auto` forwards the selected workflow's lines; headless runs use the same output without waiting for acknowledgement.
|
|
688
|
+
|
|
689
|
+
```text
|
|
690
|
+
Progress: █████░░░░░ 50% · Step 8/16 Plan Verify · Group 2 of 3
|
|
691
|
+
Progress: ███████░░░ 71% · Step 10/14 Merge Gate + Merge PR · Attempt 2 of 3
|
|
692
|
+
```
|
|
634
693
|
|
|
635
|
-
|
|
694
|
+
The line describes the current numbered position, rather than elapsed time or a count of completed rows. Flat workflows divide the current number by their distinct numbered positions. Build expands Steps 7–9 for each current plan group: with `G` groups its total is `6 + 3G + 7`; inside group ordinal `g`, completed units are `6 + 3(g - 1) + (n - 6)`, and after the loop they are `6 + 3G + (n - 9)`. Sparse group markers map to their order in the plan. A missing plan uses one group, and each emission reads the plan again, so added groups immediately change the denominator.
|
|
695
|
+
|
|
696
|
+
The percentage uses nearest-integer rounding, and the ten-cell bar uses nearest-ten rounding. Nonfinal positions are capped at 99%; the final numbered position reaches 100%. Returning to an earlier step can lower progress. Build loop lines add `Group {g} of {G}`. Retries above one add `Attempt {a} of {allowance}` from saved limits and grants, or `Attempt {a}` when no budget is known. Normal debug remediation counts completed remediation rows across every debug run, including the completion being recorded. Debug soak reuses its saved cross-run soak count on later completions. Both debug budgets include grants across every debug run. Build challenge uses its saved round, so rewriting a report within that round does not advance its budget attempt.
|
|
697
|
+
|
|
698
|
+
`steps finish`, `steps done`, recorded `context finalise`, recorded `runs dispatch` and a close that records its step expose eligible completion lines. Invalid input, a refused completion write or commit, decision and owner-pause rows, and unnumbered bookkeeping expose none. Progress is derived output and is never stored in status rows. A resume selects the same run and saved counter context.
|
|
699
|
+
|
|
700
|
+
`steps gate --progress-number` explicitly renders a gate-only completion after validation, without appending a completion row. The five Step 1 gates use their feature, month and held lock; ship's Base Check and Re-validate gates use their status file and numbers 3 and 9. Their existing step validation remains in force. Gates without the flag remain read-only validation and print no progress line; ordinary command journaling still applies.
|
|
636
701
|
|
|
637
702
|
### Gates
|
|
638
703
|
|
|
639
|
-
Every step ends `### 🔒 Gate N — {Step Name}`
|
|
704
|
+
Every step ends with `### 🔒 Gate N — {Step Name}` and a checklist.
|
|
640
705
|
|
|
641
|
-
**
|
|
706
|
+
**Remind, never restate.** A gate is a short reminder of the actions and checks the step ran, read as the orchestrator leaves the step. Every detail (conditions, routes, paths, flags, variables, value sets, field lists, exit codes, skip rules) lives in the step body and is still in the orchestrator's context. A gate item that restates a detail makes the orchestrator re-check it, and it drifts when the step changes. `bkit steps finish` / `bkit steps gate` already enforce the mechanical details.
|
|
707
|
+
|
|
708
|
+
**Format:** `[ ] {What was done}`, led by a verb, in general words. A parenthetical only says which of several like things is meant (`(@{name}, no inline work)`, `(steps gate)`). It never holds a condition, path, value or list. An action that runs on some routes only stays one plain item, because the route is in context.
|
|
642
709
|
|
|
643
710
|
Canonical patterns:
|
|
644
711
|
|
|
645
|
-
- `[ ]
|
|
712
|
+
- `[ ] Mechanical checks passed (steps finish)` / `(steps gate)` — one-call step ending / gate check
|
|
646
713
|
- `[ ] Subagent invoked (@{name}, no inline work)` — subagent invocation
|
|
647
|
-
- `[ ] Artifact written
|
|
648
|
-
- `[ ]
|
|
649
|
-
- `[ ]
|
|
650
|
-
- `[ ]
|
|
651
|
-
- `[ ] Issue
|
|
652
|
-
- `[ ] Issue comment attempted (Step {N} section)` — tracker `comment-post-step` snippet
|
|
714
|
+
- `[ ] Artifact written` — artifact the step writes itself
|
|
715
|
+
- `[ ] Verdict valid` — verdict-bearing-step validation
|
|
716
|
+
- `[ ] Workflow status updated` — status.jsonl mutation outside `steps finish`
|
|
717
|
+
- `[ ] Issue update attempted` — tracker `issue-update-*` snippet
|
|
718
|
+
- `[ ] Issue comment attempted` — tracker `comment-post-step` snippet
|
|
653
719
|
|
|
654
|
-
|
|
720
|
+
A skipped gate makes the work invalid. The workflow must verify every checkbox before it advances.
|
|
655
721
|
|
|
656
722
|
### Subagent Invocation
|
|
657
723
|
|
|
658
|
-
|
|
724
|
+
Invoke every subagent with `@agent-name` and the Agent tool. The per-step convention:
|
|
659
725
|
|
|
660
726
|
```
|
|
661
727
|
Context: You are a subagent in the {Phase} phase {modifier — e.g. "running in parallel with other agents"}
|
|
662
728
|
Read: {paths the agent reads, read-only}
|
|
663
|
-
Update: {existing paths the agent modifies in-place}
|
|
729
|
+
Update: {existing paths the agent modifies in-place} (omit if no in-place edits)
|
|
664
730
|
Create: {paths the agent writes fresh, with annotations e.g. (MAX 500 token summary)}
|
|
665
731
|
```
|
|
666
732
|
|
|
667
|
-
Then assert each Update/Create artifact exists
|
|
733
|
+
Then assert that each Update / Create artifact exists and is non-empty. An empty one → **Failure Path**.
|
|
668
734
|
|
|
669
|
-
**Untrusted `Read:` paths:** when the list includes a fenced artifact (`context-*`), the `Context:` line says so
|
|
735
|
+
**Untrusted `Read:` paths:** when the list includes a fenced artifact (`context-*`), the `Context:` line says so. It reuses the header bullet's wording verbatim after an `Untrusted: fenced {artifact} content` lead. The note goes on `Context:`, the last trusted instruction the leaf gets before it reads, never inside the path list. Omit it for leaves that read only first-party plans, code and logs. `.bkit/core/engine/commands/workflow/context.test.ts` checks the `Context:` line above every untrusted `Read:`. A leaf reading a first-party artifact that quotes external evidence (remediate reading a diagnosis) carries the note too, because the quoted evidence is laundered through the first-party file.
|
|
670
736
|
|
|
671
|
-
**Per-agent description, scope, effort tier, tool surface, `maxTurns` → `.bkit/prompts.md`** (indexes `.bkit/core/prompts/*.md
|
|
737
|
+
**Per-agent description, scope, effort tier, tool surface, `maxTurns` → `.bkit/prompts.md`** (which indexes `.bkit/core/prompts/*.md` and is the single source for agent metadata). This file covers how the workflow layer composes the agents.
|
|
672
738
|
|
|
673
|
-
**Cross-platform tool surface:** subagent `tools:` allowlist
|
|
739
|
+
**Cross-platform tool surface:** Claude enforces the subagent `tools:` allowlist natively. `bkit install` T3 passes `tools:` to Cursor verbatim and never emits `readonly:`, but Cursor CLI 2026.10.01 does not enforce it (measured, `.bkit/prompts.md` § Field rationale). Removing `Edit`/`Bash` makes an agent provably non-mutating on Claude only.
|
|
674
740
|
|
|
675
741
|
**Parallel fan-outs** (effort / model diversity, sibling-blind):
|
|
676
742
|
|
|
@@ -679,344 +745,415 @@ Then assert each Update/Create artifact exists, non-empty. Empty → **Failure P
|
|
|
679
745
|
| --- | --- | --- |
|
|
680
746
|
| `@bkit-design-brainstorm-ideate-1` / `-2` / `-3` | `/bkit-design` Step 4 | Each agent's prompt forbids reading any sibling output. Triplet — pragmatic / optimal-tradeoff / risk-premortem lenses. |
|
|
681
747
|
| `@bkit-design-review-1` / `-2` | `/bkit-design` Step 6 | Same; pair. |
|
|
682
|
-
| `@bkit-plan-review-1` / `-2`
|
|
683
|
-
| `@bkit-plan-scope-check-1` / `-2` | `/bkit-plan` Step 7 | Same; pair. |
|
|
684
|
-
| `@bkit-ship-update-docs` / `@bkit-ship-summary` | `/bkit-ship` Step 6 | `bkit-ship-summary` must not read `update-docs.md`. |
|
|
748
|
+
| `@bkit-plan-review-1` / `-2` + `@bkit-plan-scope-check` | `/bkit-plan` Step 5 | Same; three agents — plan text (tightness, dependency order) / code (regression risk) / scope check. |
|
|
685
749
|
|
|
686
750
|
### Verdict vocabulary
|
|
687
751
|
|
|
688
|
-
|
|
752
|
+
Verdict-bearing agents with a meaningful "addressable" middle state use the 3-way `PASS | CONCERNS | FAIL`. Atomic-action agents, whose outcome is binary (succeeded or didn't), use the 2-way `PASS | FAIL`:
|
|
689
753
|
|
|
690
754
|
<!-- prettier-ignore -->
|
|
691
755
|
| Agent | `Verdict` values | Routing |
|
|
692
756
|
| --- | --- | --- |
|
|
693
|
-
| `@bkit-build-plan-current` | PASS / CONCERNS / FAIL | PASS → Step
|
|
694
|
-
| `@bkit-build-plan-verify` | PASS / CONCERNS / FAIL | PASS →
|
|
695
|
-
| `@bkit-build-challenge-
|
|
696
|
-
| `@bkit-design-review-1` / `-2` | PASS / CONCERNS / FAIL | `REVIEW_VERDICT` = worst-of-two. PASS/CONCERNS → Step 7 spike (`
|
|
697
|
-
| `@bkit-design-spike` | PASS / CONCERNS / FAIL | Every value → Step 8 apply-review; the step informs, it does not gate. PASS = every claim held under an honest attempt; CONCERNS = nothing disproven but a claim was unsettleable this run (missing credential / service / host), design proceeds with the assumption unproven and
|
|
698
|
-
| `@bkit-design-update` | PASS / CONCERNS / FAIL |
|
|
699
|
-
| `@bkit-design-organise` | PASS / CONCERNS / FAIL | PASS/CONCERNS → Step 10 summary; FAIL → Failure Path (
|
|
700
|
-
|
|
|
701
|
-
|
|
|
757
|
+
| `@bkit-build-plan-current` | PASS / CONCERNS / FAIL | PASS → Step 6. CONCERNS / FAIL → Step 6 too — advisory only: recorded on the `step-done` row, posted to the tracker with `Affected`, echoed as a console advisory, never blocking. The findings flow into Step 7: `@bkit-build-plan-tasks` reads `build-plan-current.md` and treats it as fact about the codebase, the plan as intent. Build never revises the plan file — that belongs to `/bkit-plan`, whose own close re-stamps the anchor. Never invokes `@bkit-plan-update`. |
|
|
758
|
+
| `@bkit-build-plan-verify` | PASS / CONCERNS / FAIL | PASS → group gate (when a later group exists; § Group gate) → next group, or Step 10 when none is open; CONCERNS / group gate FAIL → `@bkit-build-plan-gaps-remediate` loop, never asked while `build.verify.maxAttempts` allows; no round left → § Decision Pause (`VERIFY_GAPS`), or Failure Path for a group gate FAIL alone; FAIL (any gap `Fixable: false`) → one fixable-only remediate when `Fixable: true` and a round is left, then § Decision Pause. |
|
|
759
|
+
| `@bkit-build-challenge-1` / `-2` | PASS / CONCERNS / FAIL | The step row's verdict = worst of the reports (one on a small change), `failures` = their sum; it records, it does not route. `bkit challenge merge` routes on the findings: `none` → Step 12; `fix` → Step 7 for the new last group the merge appended; `pause` → Decision Pause. Findings carry `class: mechanical \| architectural`; architectural → `**Fixable:** false`. |
|
|
760
|
+
| `@bkit-design-review-1` / `-2` | PASS / CONCERNS / FAIL | `REVIEW_VERDICT` = worst-of-two. PASS / CONCERNS → Step 7 spike (`REVIEW_SPIKE` = true) else Step 8 apply-review; FAIL → Failure Path (design fundamentally not viable, human reframe required). `@bkit-design-review-1` additionally emits `Spike` (`true` / `false`) in its header — a routing flag, not a verdict; `REVIEW_SPIKE` gates Step 7 only and never contributes to `REVIEW_VERDICT`. |
|
|
761
|
+
| `@bkit-design-spike` | PASS / CONCERNS / FAIL | Every value → Step 8 apply-review; the step informs, it does not gate. PASS = every claim held under an honest attempt; CONCERNS = nothing disproven but a claim was unsettleable this run (missing credential / service / host), design proceeds with the assumption unproven and the design summary lists it as a CONCERNS reason; FAIL = a claim is disproven and `@bkit-design-update` revises the design against the evidence — not a Failure Path, a disproven assumption is the step succeeding. Only a malformed or empty artifact routes to the Failure Path. Per-claim `SETTLED` / `DISPROVEN` / `BLOCKED` stays in the artifact body — the header verdict is the routing signal, not the finding. |
|
|
762
|
+
| `@bkit-design-update` | PASS / CONCERNS / FAIL | PASS / CONCERNS → Step 9 design-organise; FAIL (a CRITICAL item left unapplied) → Failure Path. CRITICAL items applied, OPTIONAL applied on merit, `OUT OF SCOPE` deferred. |
|
|
763
|
+
| `@bkit-design-organise` | PASS / CONCERNS / FAIL | PASS / CONCERNS → Step 10 summary; FAIL → Failure Path (a self-verify check, such as a cycle, still failing after 2 fix iterations; human review required). |
|
|
764
|
+
| `@bkit-plan-review-1` / `-2` + `@bkit-plan-scope-check` | PASS / CONCERNS / FAIL | The step row's verdict = worst of the three, `failures` = their sum. PASS / CONCERNS → Step 6 apply-review, where `@bkit-plan-update` repairs every CRITICAL finding; FAIL → Failure Path. FAIL is reserved for what no plan edit fixes (a task-order cycle no reorder resolves, a plan contradicting its source design, a regression vector the design itself requires, a `Blocking` out-of-scope deferral no edit recovers), so a human reframes the design or the issue. |
|
|
765
|
+
| `@bkit-plan-update` | PASS / CONCERNS / FAIL | PASS / CONCERNS → Step 7; FAIL (a CRITICAL item left unapplied) → Failure Path. CRITICAL items applied, OPTIONAL applied on merit. |
|
|
766
|
+
| `bkit workflows summary` (`design`, `plan`, `build`, `debug`, `ship`) | PASS / CONCERNS / FAIL | PASS or CONCERNS → close workflow / next step; FAIL → Failure Path. |
|
|
767
|
+
| `@bkit-build-plan-tests` | PASS / HANDOVER / FAIL | `HANDOVER` (turn cap near, planned tests left neither `WROTE` nor `BLOCKED`) → Step 7 re-runs the tests half once for that group as a handover, not a failed attempt, its tests brief leaving out the tests already proved red; else → `tests red`, which judges the tests, not the verdict. A re-run keeps the existing log and resets its `Verdict` to `PENDING`. |
|
|
768
|
+
| `@bkit-build-plan-tasks` | PASS / HANDOVER / FAIL | `HANDOVER` (turn cap near, tasks left neither `DONE` nor `BLOCKED`, even when another task ended `BLOCKED`), or a group task with no `DONE` / `BLOCKED` line → Step 7 re-runs once for that group as a handover, not a failed attempt, its briefs leaving out the `DONE` tasks and the tests already proved red; else → Step 8, which judges the log. A re-run keeps the existing log and resets its `Verdict` to `PENDING`. |
|
|
769
|
+
| 2-way agents (`@bkit-debug-abort-handover`, `@bkit-design-generate`, `@bkit-design-brainstorm-ideate-1/2/3`, `@bkit-ship-update-docs`, `@bkit-ship-conflict-resolve`, `@bkit-ship-deferred-sweep`) | PASS / FAIL | PASS → continue; FAIL → Failure Path. Atomic action — no middle state (cannot proceed → fail; no partial-progress CONCERNS). For `@bkit-ship-conflict-resolve`: PASS means its re-run of `bkit branches sync --merge` committed the merge, and Step 4 pushes; FAIL aborts the merge and routes to `@bkit-debug-abort-handover`. For `@bkit-ship-deferred-sweep`: PASS → Merge (Step 6); FAIL touches `docs/plans/{YYYYMM}/logs/{FID}/.deferred-blocked` and routes to `@bkit-debug-abort-handover` (merge never happens). FAIL only on >=1 of four blocking tests (behaviour / safety / false green / consumer break); a gap passing none joins the third track `Lazy (unjustified)`, orthogonal to the verdict — recorded in `docs/deferrals.jsonl` (`reason` = `unjustified`; new `key` unplanned, own `key` re-appended when adjudicated) and resurfaced, never merged against. |
|
|
702
770
|
|
|
703
771
|
### Retry / timeout / iteration constants
|
|
704
772
|
|
|
705
773
|
<!-- prettier-ignore -->
|
|
706
774
|
| Constant | Value | Where |
|
|
707
775
|
| --- | --- | --- |
|
|
708
|
-
|
|
|
709
|
-
| `
|
|
710
|
-
| `MAX_CHALLENGE_REMEDIATE_ATTEMPT` | 1 | `/bkit-build` challenge→remediate passes (one re-Challenge bite) |
|
|
711
|
-
| `MAX_DEBUG_ATTEMPT` | 3 | `/bkit-debug` invocation index (read from status.jsonl `workflow == "debug"` entry); `DEBUG_ATTEMPT` >= `MAX_DEBUG_ATTEMPT` starts a fresh run in `SOAK` |
|
|
712
|
-
| `MAX_NORMAL_ATTEMPT` | 3 | `/bkit-debug` NORMAL diagnose→remediate loop |
|
|
713
|
-
| `MAX_SOAK_ATTEMPT` | 3 | `/bkit-debug` SOAK loop (reset to 0 on each SOAK entry) |
|
|
714
|
-
| `MAX_MERGE_ATTEMPT` | 3 | `/bkit-ship` PR merge retries |
|
|
715
|
-
| `MAX_REVALIDATE_ATTEMPT` | 3 | `/bkit-ship` poll-only Step 9 re-entries after a gate refusal (10/11/14/17) |
|
|
716
|
-
| `MAX_DEV_DISPATCH_ATTEMPTS` | 3 | `bkit-cloud.yml` — distinct failed `dev` CI SHAs per FID that may each dispatch `/bkit-debug` |
|
|
717
|
-
| Grill rounds | 10 | `/bkit-design` Step 3 interview cap, draft scenario round included (decision rounds <= 9); literal in the step, not in `THRESHOLDS` |
|
|
718
|
-
| Step timeout | 3600s | Any workflow or subagent run exceeding this → Failure Path; `/bkit-design` Step 3 time waiting on human answers does not count |
|
|
776
|
+
| Ask point limits | 2 each; grill 6 turns | `package.json` `bkit.workflows.<workflow>.<point>` (§ Ask points); read by `bkit counters max` / `route --point=` |
|
|
777
|
+
| Dev-CI debug dispatches | `debug.fix` + `debug.soak` `maxAttempts` | `bkit-cloud.yml` — distinct failed `dev` CI SHAs per FID that may each dispatch `/bkit-debug`; read from `package.json` with `jq` (the router runs before bkit is installed), falling back to 2 each as the engine does |
|
|
719
778
|
| Lock idle threshold | 1800s | Concurrent-run cut-off: holder `IN_PROGRESS` with last-step age <30min → Failure Path; any other holder reclaimed at once (`WORKFLOW_LOCK_IDLE_S`, `commands/workflow/locks.ts`) |
|
|
720
779
|
| Close retries | 10 / 2s→30s | every dev landing (design / plan / ship close, ship Failure Path record, build / debug roadmap mirror): pushes when `dev` moved underneath; design / plan PR merge tries (`LAND_ATTEMPTS` each); wait before each retry doubles from `LAND_BACKOFF_START_S` up to `LAND_BACKOFF_CAP_S`, jittered down by up to half — at most 3min of waiting in all |
|
|
721
780
|
| Ship CI wait | 1800s / 30s | Step 9 completion poll budget / interval (`SHIP_CI_WAIT_TIMEOUT_S` / `SHIP_POLL_INTERVAL_S`) |
|
|
722
781
|
| Ship presence probe | 6 x 10s | Step 9 run-at-head probe before any dispatch (`SHIP_PROBE_ATTEMPTS` x `SHIP_PROBE_INTERVAL_S`) |
|
|
723
782
|
| Newest-bkit lookup | 5s / 86400s / 3600s | Registry query limit / answer reuse / failure reuse for the outdated-bkit check (`BKIT_LATEST_LOOKUP_TIMEOUT_S` / `BKIT_LATEST_CACHE_S` / `BKIT_LATEST_RETRY_S`) |
|
|
724
783
|
|
|
725
|
-
|
|
784
|
+
Ask point limits live in `CONFIG_DEFAULTS.asks` (`.bkit/core/engine/shared/settings.ts`), overridden per repo in `package.json`, and are read by ask point in routing blocks (`bkit counters route --point=`) — never a literal. Fixed repair retries (the subagent header re-ask, the plan check fix, the convert retry, `LAND_ATTEMPTS`, the `gh` → MCP switch, the tracker retry, the CI wait) keep no setting. Waits live in `TIMEOUTS` (`.bkit/core/engine/shared/timeouts.ts`).
|
|
726
785
|
|
|
727
786
|
### Failure Path
|
|
728
787
|
|
|
729
|
-
Every command has
|
|
788
|
+
Every command has a `🤖 Failure Path` section before Step 1. Any step, tool or gate failure triggers it.
|
|
730
789
|
|
|
731
790
|
**Standard failure (always):**
|
|
732
791
|
|
|
733
|
-
1. Write the error text to `{OUTBOX_ROOT}/error.md`, then one call: `bkit workflows fail --workflow= --fid= --month= --token={LOCK_TOKEN} [--max-exceeded] {LABEL_FLAGS} --step-number= --step-title= --sub-step= --error-file="{OUTBOX_ROOT}/error.md" [--stderr-file=]` (ship adds `--pr=`). State is changed only with a `--token
|
|
734
|
-
2.
|
|
792
|
+
1. Write the error text to `{OUTBOX_ROOT}/error.md`, then one call: `bkit workflows fail --workflow= --fid= --month= --token={LOCK_TOKEN} [--max-exceeded] {LABEL_FLAGS} --step-number= --step-title= --sub-step= --error-file="{OUTBOX_ROOT}/error.md" [--stderr-file=]` (ship adds `--pr=`). State is changed only with a `--token`. An empty one counts as absent, because the failure came before Step 1 took the lock. With a token, the call appends `workflow-failed` (nothing when `status.jsonl` does not exist yet), aborts a rebase or merge in progress in the run's worktree, releases the caller's own lock (another owner's stays, reported as `lock.heldBy`), clears the sentinels (`.rebase-failed`; ship `.deferred-blocked`). Exit 5 = the lock file survived; the printed comment already says `Lock removal failed`. It always prints `labels` (the current labels plus `bkit:failed`; a ship whose `--pr` already MERGED also moves to `bkit:merged`), `trackerState`, `handoverNeeded` (`--max-exceeded`, a sentinel existed, or a debug run in `SOAK`), and the `### Workflow Failure` `comment`. No dev push.
|
|
793
|
+
2. `--post` posts `comment` and writes the labels and state (`tracker`, `labelsWrite`). If either prints `done` = false, the tracker MCP does that write.
|
|
735
794
|
|
|
736
|
-
**Conditional handover** — only when `handoverNeeded` **and** a worktree exists
|
|
795
|
+
**Conditional handover** — only when `handoverNeeded` **and** a worktree exists. The handover agent `cd`s to `{WORKTREE_PATH}`. `/bkit-debug` decides `DEBUG_MODE` at Step 1, before the worktree exists, so a failure before the worktree goes straight to STOP:
|
|
737
796
|
|
|
738
797
|
3. `@bkit-debug-abort-handover` with prior logs as Read; Write `docs/plans/{YYYYMM}/logs/{FID}/{phase}-handover.md`.
|
|
739
798
|
|
|
740
|
-
**Keep the record (always; design / plan / build / debug)** — skipped only when `{WORKTREE_PATH}` is not set
|
|
799
|
+
**Keep the record (always; design / plan / build / debug)** — skipped only when `{WORKTREE_PATH}` is not set, because the failure came before the run had a tree and no row was written:
|
|
741
800
|
|
|
742
|
-
4. `bkit workflows handover --workflow= --fid= --month= --push --worktree="{WORKTREE_PATH}"`, run in the run's tree:
|
|
743
|
-
- **Feature branch:** `git add -A` → commit `docs({FID}): {phase} aborted bkit [skip ci]` (handover or not) → push `--mode=abort`.
|
|
744
|
-
- **`dev` / `main` / detached** (debug adopting `dev` / `main`): nothing staged, committed or pushed from the checkout; half-done code never reaches a shared branch. Only the run's own record is carried into a throwaway `origin/dev` checkout: the `.md` logs it wrote in its log folder, that folder's `.jsonl` lines `HEAD` lacks, and the uncommitted rows of that workflow at or after the run's `workflow-started` in `docs/*.jsonl` / `.bkit/*.jsonl` (not `.bkit/issues.jsonl
|
|
801
|
+
4. `bkit workflows handover --list-stray` (same flags, no push) prints `shared` (on `dev` / `main` / detached), `modified` and `untracked` paths outside the run's log folder; on a feature branch the orchestrator removes the unintended ones. Then `bkit workflows handover --workflow= --fid= --month= --push --worktree="{WORKTREE_PATH}"`, run in the run's tree:
|
|
802
|
+
- **Feature branch:** `git add -A` minus the `bkit.workflows.worktree.copy` entries (`.env` never lands) → commit `docs({FID}): {phase} aborted bkit [skip ci]` (handover or not) → push `--mode=abort`. With an open PR it exits 9 and does not push, because a `[skip ci]` head empties the PR's check rollup. The record stays committed locally. `gh` cannot answer → exit 80, no push → probe via `list_pull_requests`, re-run with `--open-pr=<n>|none`.
|
|
803
|
+
- **`dev` / `main` / detached** (debug adopting `dev` / `main`): nothing staged, committed or pushed from the checkout; half-done code never reaches a shared branch. Only the run's own record is carried into a throwaway `origin/dev` checkout: the `.md` logs it wrote in its log folder, that folder's `.jsonl` lines `HEAD` lacks, and the uncommitted rows of that workflow at or after the run's `workflow-started` in `docs/*.jsonl` / `.bkit/*.jsonl` (not `.bkit/issues.jsonl` or the stats script's `chat` / `run` rows; no start row → none) → one `chore({FID}): {phase} FAILED bkit [skip ci]` commit, as ship's flush. Refused / out of retries → exit 10; fetch / checkout failure → exit 11; record stays in the checkout. A run in place on `dev` also keeps its own commits on local `dev` unpushed (the Failure Path never pushes them), and the hand-back never resets or removes a path its shared-checkout record lists, nor carries the record's foreign ledger rows; the record is removed once the hand-back has run. Landed → hand-back removes from the checkout only what was carried, so a later `dev` fast-forward does not stop on it: a carried log identical to the landed copy → removed (untracked) or restored to `HEAD` (tracked); a carried ledger loses exactly the carried lines (equal to `HEAD` → restored; untracked and empty → removed). Staged paths, or a log changed since it landed, stay, logged.
|
|
745
804
|
- Prints the `### Workflow Handover` `comment` (null without a handover): blob link at the pushed ref (none if nothing pushed) + verbatim body; the orchestrator posts it.
|
|
746
805
|
|
|
747
806
|
5. **STOP** — no downstream steps.
|
|
748
807
|
|
|
749
|
-
**Ship exception:** no separate abort commit, no second push. After the optional handover subagent, `bkit workflows handover --workflow=ship --flush --worktree=` carries the book (handover, deferred-sweep, ledger rows) into a throwaway `origin/dev` checkout →
|
|
808
|
+
**Ship exception:** no separate abort commit, no second push. After the optional handover subagent, `bkit workflows handover --workflow=ship --flush --worktree=` carries the book (handover, deferred-sweep, ledger rows) into a throwaway `origin/dev` checkout → one `chore({FID}): ship FAILED bkit [skip ci]` commit and one push to `dev` (`dev` moved → rebuilt and pushed again; refused → the record stays in `BOOK_ROOT` for the next ship of `{FID}`). It never touches the open PR's validated head, so the open-PR guard does not apply, and the handover survives the branch prune. The comment is posted only when `handoverNeeded`, and linked only where the flush pushed.
|
|
750
809
|
|
|
751
810
|
`/bkit-design` and `/bkit-plan` run no handover subagent (no max-retry loop); they still keep the record.
|
|
752
811
|
|
|
753
812
|
### Rebase Conflict Tiering
|
|
754
813
|
|
|
755
|
-
`/bkit-build`, `/bkit-debug`, `/bkit-design`, `/bkit-plan` Step 2 rebase a resumed feature worktree onto its base, `origin/dev` or local `dev` when it is ahead
|
|
814
|
+
`/bkit-build`, `/bkit-debug`, `/bkit-design`, `/bkit-plan` Step 2 rebase a resumed feature worktree onto its base (`bkit worktrees setup`): `origin/dev` for design / plan, and for build / debug `origin/dev` or local `dev` when it is ahead. `/bkit-ship` never rebases its branch: Step 4 merges `origin/dev` into it locally (`bkit branches sync --merge`) and pushes plain. Recovery has three tiers:
|
|
756
815
|
|
|
757
816
|
<!-- prettier-ignore -->
|
|
758
817
|
| Tier | Conflict shape | Recovery | Mechanism |
|
|
759
818
|
| --- | --- | --- | --- |
|
|
760
819
|
| 1 | Append-only ledgers (`docs/knowledge.jsonl`, `docs/decisions.jsonl`, `docs/deferrals.jsonl`, `docs/failures.jsonl`, `.bkit/issues.jsonl`, `docs/roadmap.md`, `.bkit/stats.jsonl`) + per-FID `status.jsonl` (`docs/plans/**/status.jsonl`) | `merge=union` — git auto-concatenates both sides | `.gitattributes` (template at `.bkit/shared/.gitattributes`, installed to consumer roots by `bkit install`); conflict never reaches the workflow |
|
|
761
|
-
| 2 | Any combination of the Tier-1 ledgers, `.bkit/friction.jsonl`,
|
|
762
|
-
| 3 | Code, configs, anything else | `bkit branches rebase` refuses (exit 3), aborts the rebase, and writes sentinel `docs/plans/{YYYYMM}/logs/{FID}/.rebase-failed` → Failure Path → conditional handover (`bkit workflows fail` reports `handoverNeeded`) | Sentinel-file pattern
|
|
820
|
+
| 2 | Any combination of the Tier-1 ledgers, `.bkit/friction.jsonl`, the dependency lockfile (pnpm, npm, yarn, bun, cargo, go, uv), a generated register (`docs/capabilities.md`, `REGISTERS` in `.bkit/core/engine/commands/workflow/branches.ts`), an embedding doc (a doc the register's script copies a generated block into, listed by `GRAPH_EMBED_DOCS` in the repo's `scripts/graphify/bkit-graphify.sh`; the shipped template lists none), and the install record (`.bkit/version`) | `bkit branches rebase` — union-resolves each ledger (`git merge-file --union` over the three index stages), takes the rebase target's lockfile and regenerates it (`LOCKFILE_REGENERATE`, `.bkit/core/engine/shared/package-manager.ts`), takes the rebase target's copy of a register and carries the branch's edit to its hand-written region (the overrides block) onto it, takes the rebase target's copy of an embedding doc's generated block and merges the rest of that doc as git would, merges the install record entry by entry (each entry takes the side that changed it, and the rebase target's value when both did), then drives `--continue` / `--skip` to completion. Once the rebase completes it runs the register's rebuild script (`scripts/graphify/bkit-graphify.sh refresh`) when that script exists, and commits only the paths the rebuild changed. The install record needs no rebuild: `bkit upgrade` refreshes a fingerprint left at the target's value once the file matches what bkit writes, and until then treats that file as edited by hand. When both sides changed the hand-written region, an embedding doc still conflicts outside its generated block, or a side deleted the install record, the rebase refuses, as in Tier 3. A rebuild that fails, or a missing script, leaves the target's copy and does not fail the rebase: the pre-push gate, CI and ship's `bkit:generate` still judge the register | `bkit worktrees setup` exits 3 on a conflicted resume rebase and leaves it in progress → Step 2 runs `bkit branches rebase --sentinel= --log-file= --file=` → re-runs `setup`; non-zero → Failure Path. A completed rebase writes one `engine-action` row (`action: rebase`, key `rebase/<old HEAD>`, ref the new HEAD) to `status.jsonl`, from `setup` itself or from `--file=`, so a rewritten branch history is on the record |
|
|
821
|
+
| 3 | Code, configs, anything else | `bkit branches rebase` refuses (exit 3), aborts the rebase, and writes sentinel `docs/plans/{YYYYMM}/logs/{FID}/.rebase-failed` → Failure Path → conditional handover (`bkit workflows fail` reports `handoverNeeded`) | Sentinel-file pattern. In `/bkit-ship` Step 4, `bkit branches sync --merge` resolves the merge's ledgers, lockfile, generated register, embedding docs and install record itself, leaves the other paths conflicted with the merge in progress, writes no sentinel and exits 24 (`pending`); the workflow then invokes `@bkit-ship-conflict-resolve`, which resolves them by hand and runs the block again, which commits the merge. A ledger, lockfile, register, embedding-doc or install-record resolution that fails aborts the merge and writes the sentinel |
|
|
763
822
|
|
|
764
|
-
**Why Tier 1 `merge=union` not workflow step:** trade-off
|
|
823
|
+
**Why Tier 1 `merge=union` not workflow step:** the trade-off is interleaved or duplicated rows when both sides append. Readers de-dupe on an identity tuple (`(kind, repo, key)`), so that is not a regression. `.gitattributes` is the standard git mechanism and pre-empts the conflict for all callers. It excludes `.bkit/friction.jsonl`, because same-`key` updates break the strict-append union safety.
|
|
765
824
|
|
|
766
|
-
**Why Tier 2 when Tier 1 covers the ledgers:** Tier 1 fires only where the attribute applies
|
|
825
|
+
**Why Tier 2 when Tier 1 covers the ledgers:** Tier 1 fires only where the attribute applies. It does not fire when the consumer's `.gitattributes` predates a ledger, when there is none, or for `.bkit/friction.jsonl` (which ships unlisted). Those conflicts reach the workflow. Tier 2 runs `git merge-file --union` over index stages `:1:` / `:2:` / `:3:`, the same driver as `merge=union`, so its output is byte-identical to a path the attribute pre-empted.
|
|
767
826
|
|
|
768
|
-
**Why Tier 2 covers `.bkit/friction.jsonl` when Tier 1 excludes it:** the exclusion guards
|
|
827
|
+
**Why Tier 2 covers `.bkit/friction.jsonl` when Tier 1 excludes it:** the exclusion guards harvest drains, because union can resurrect a drained row. At rebase time that is the cheaper error: the next harvest re-banks the row idempotently, while a blocking conflict halts the run. This divergence from the attribute is deliberate.
|
|
769
828
|
|
|
770
|
-
**Why Tier 2 is a command, not inline bash:** inline
|
|
829
|
+
**Why Tier 2 is a command, not inline bash:** inline, it would be four copies of ~150 lines across four workflows. It is not a subagent, because it is mechanical, deterministic git plumbing with no judgement.
|
|
771
830
|
|
|
772
|
-
**Tier 2 refuses before it mutates:**
|
|
831
|
+
**Tier 2 refuses before it mutates:** it classifies the whole conflicted set first, so a refused path never leaves half the set rewritten. Refusal aborts the rebase at once (`git rebase --abort`, before the log and sentinel writes), unwinding partial resolutions; the Failure Path's `bkit workflows fail` aborts any rebase or merge still in progress.
|
|
773
832
|
|
|
774
|
-
**Why Tier 3 `@bkit-ship-conflict-resolve` only in `/bkit-ship`:** ship
|
|
833
|
+
**Why Tier 3 `@bkit-ship-conflict-resolve` only in `/bkit-ship`:** ship merges the active integration target into its branch, so conflicts are common. `/bkit-build`/`/bkit-debug` work on an isolated feature branch, where conflicts are rarer and point to deeper problems, so they get the sentinel and a handover only. The resolver's verdict (`bkit:gate:install-static-unit-build` PASS) is necessary but not sufficient, because tests can pass while intent was dropped, so the resolver refuses semantic overlaps and hands over on ambiguity. `bkit-debug` is not repurposed for git plumbing, because diagnose / remediate are scoped to test and runtime failures.
|
|
775
834
|
|
|
776
|
-
**Failure Path routing:** rebase sentinel → conditional handover via `@bkit-debug-abort-handover` (same as max-retry) → handover doc, `Failed` label, `In Review
|
|
835
|
+
**Failure Path routing:** a rebase sentinel → conditional handover via `@bkit-debug-abort-handover` (the same as max-retry) → handover doc, `Failed` label, `In Review`. It is never a silent stop.
|
|
777
836
|
|
|
778
837
|
### `bkit [auto route]` Marker Propagation
|
|
779
838
|
|
|
780
|
-
`bkit [auto route]`
|
|
839
|
+
`bkit [auto route]` is the CI commit-message marker that enables the free-tier `bkit-cloud.yml` auto-route gate. It goes on the close-workflow commit (and debug's re-trigger commit), only when the issue carried `bkit:auto`. The gate reads one commit's `head_commit.message`, so an unmarked commit on top buries the marker. Build / debug therefore re-read `bkit:auto` immediately before they construct the CI-triggering HEAD. The marker does not suppress CI (the HEAD-Subject Assertion is a deny-list, so it passes automatically).
|
|
781
840
|
|
|
782
|
-
**Ship does not carry the marker on the feat-branch HEAD; it does carry it on the squash-merge subject.** Ship's integrate step authors
|
|
841
|
+
**Ship does not carry the marker on the feat-branch HEAD; it does carry it on the squash-merge subject.** Ship's integrate step authors a HEAD only on Path B: `bkit branches sync --merge` commits the carried work, the `origin/dev` merge and the `bkit:generate` output as `chore({FID}): …` commits without the marker, so those commits bury it by construction. On Path A, ship authors no integrate commit. Its only code commit before the merge is Step 10's regenerate round, `fix({FID}): regenerate attempt {N}`, with no marker, so its push runs CI. The merge moves the PR head past the one CI validated, and that is deliberate: ship re-validates itself at Step 9, waiting on a run at the merged head and polling it to completion, so it never needs the router to route back into it. The re-validation is a presence probe, then `gh workflow run {bkit.testing.ciWorkflow}` when no run exists at the validated head. No Step 4 commit carries a skip token, so the Step 4 push starts a run at the merged head, and the probe finds that run instead of dispatching a second one.
|
|
783
842
|
|
|
784
843
|
Step 10's `bkit prs merge --label=…` appends ` bkit [auto route]` to the squash subject when the re-read labels hold `bkit:auto` (`bkit-ship.md` Step 10). The squash commit is what lands on `dev`; `bkit-cloud.yml`'s free-tier gate reads its `head_commit.message` to admit the post-merge `dev` CI trigger. GitHub authors it at merge time rather than pushing onto a validated head.
|
|
785
844
|
|
|
786
|
-
**Accepted residual:** after
|
|
845
|
+
**Accepted residual:** after Step 4 the feat-branch HEAD is unmarked, so the cloud router cannot auto-recover a ship run that dies mid-flight. The operator re-runs it via `workflow_dispatch`. That is the accepted trade for never mutating a validated head. The residual is scoped to the feat-branch HEAD only; the squash-merge subject legitimately carries the marker (see above).
|
|
787
846
|
|
|
788
847
|
**Placement (mode-dependent):**
|
|
789
848
|
|
|
790
|
-
- `/bkit-build` Step
|
|
791
|
-
- `/bkit-debug` Step 11 PR-mode: same
|
|
792
|
-
- `/bkit-debug` Step 11 local-mode: `bkit:auto` re-read before the create-pr commit (sub-step
|
|
793
|
-
- `/bkit-ship` Step 4 (
|
|
794
|
-
- `/bkit-ship` Step 10 (squash-merge subject, `dev`): labels re-read
|
|
849
|
+
- `/bkit-build` Step 16: `bkit:auto` is re-read before the close-workflow commit. If present, the subject is `chore({FID}): close-workflow bkit [auto route]`. The close-workflow commit is the feat-branch HEAD that fires CI, so the gate checks its `head_commit.message`.
|
|
850
|
+
- `/bkit-debug` Step 11 PR-mode: the same, with the marker on close-workflow (sub-step 2). Create-pr (sub-steps 5-6) does not run (`TRIGGER_PR=0`).
|
|
851
|
+
- `/bkit-debug` Step 11 local-mode: `bkit:auto` is re-read before the create-pr commit (sub-step 6). The marker goes on create-pr, which is the CI-triggering HEAD in local mode.
|
|
852
|
+
- `/bkit-ship` Step 4 (feat-branch HEAD): no placement — see "Ship does not carry the marker on the feat-branch HEAD" above. Cloud gate in-job `bkit:auto` re-check = live kill switch.
|
|
853
|
+
- `/bkit-ship` Step 10 (squash-merge subject, `dev`): labels re-read (`bkit issues fetch --outbox`, the tracker MCP on exit 80) in the merge sub-step and passed to `bkit prs merge` as `{LABEL_FLAGS}` — never carried forward from Step 1's `{LABELS}`. `bkit:auto` present → ` bkit [auto route]` appended to the subject. This is the commit that fires the post-merge `dev` free-tier gate — the only marker `/bkit-ship` places.
|
|
795
854
|
|
|
796
|
-
**Why re-read must precede commit:** kill-switch re-read at build Step
|
|
855
|
+
**Why re-read must precede commit:** the kill-switch re-read at build Step 16 / debug Step 11 sub-step 9 runs after the commit and push, so it cannot put the marker on a commit that already exists. A fresh `bkit:auto` read before the commit is built is the authoritative "at close time" signal.
|
|
797
856
|
|
|
798
|
-
**Coexistence with `bkit [verbose ci]`:** debug local
|
|
857
|
+
**Coexistence with `bkit [verbose ci]`:** in debug local mode both go on the same subject: `chore({FID}): close-workflow bkit [verbose ci] bkit [auto route]`. The HEAD-Subject Assertion accepts both. The gate reads `bkit [auto route]` via `contains(head_commit.message, 'bkit [auto route]')`, so `bkit [verbose ci]` does not interfere.
|
|
799
858
|
|
|
800
|
-
**Cleanup:**
|
|
859
|
+
**Cleanup:** the marker clears itself on each push. Close-workflow, the debug re-trigger and the ship squash-merge subject carry it; ship's own feat-branch HEAD (Step 4) never does. There is no PR-title edit (unlike `bkit [verbose ci]` in debug PR mode), because auto-route fires on the commit message.
|
|
801
860
|
|
|
802
861
|
### `bkit [verbose ci]` Marker Propagation
|
|
803
862
|
|
|
804
|
-
`bkit [verbose ci]`
|
|
863
|
+
`bkit [verbose ci]` is the CI commit-message / PR-title marker (`docs/deployments.md` § Commit-message force tags) that raises log detail for one run. `/bkit-debug` applies it automatically on every CI-triggering push (retry evidence). `/bkit-build` and `/bkit-ship` never apply it. For the env block, see the template bkit-ci.yml `bkit-tests-static` job-level `env:`. For the knob list, see `docs/testing.md` § "CI verbosity".
|
|
805
864
|
|
|
806
865
|
**Why debug always-verbose, build never:**
|
|
807
866
|
|
|
808
|
-
- **Debug = failure-recovery.** Verbose every push
|
|
809
|
-
- **Build = happy-path / ship-eligible.** Verify
|
|
810
|
-
- **Ship = green-path.** Verbose on green runs
|
|
867
|
+
- **Debug = failure-recovery.** Verbose on every push means attempt N+1's diagnose reads rich logs from attempt N's verify. That removes the one-cycle delay of "verbose only on retry".
|
|
868
|
+
- **Build = happy-path / ship-eligible.** Verify retries are local, and only the final summary / create-pr / close-workflow pushes run CI, so verbose would carry downstream onto ship. Verbose starts when the build Failure Path triggers `/bkit-debug`.
|
|
869
|
+
- **Ship = green-path.** Verbose on green runs costs storage and time and gives no diagnostic payoff.
|
|
811
870
|
|
|
812
871
|
**Mode-dependent propagation (`/bkit-debug`):**
|
|
813
872
|
|
|
814
|
-
GitHub Actions
|
|
873
|
+
GitHub Actions reads `push.head_commit.message` or `pull_request.title`. The template bkit-ci.yml has `on:` `branches: [main, dev]`, so feature pushes fire `pull_request.synchronize`, not `push`. `PUSH_MODE` (Step 1 sub-step 6, `bkit prs probe --base=dev`) decides where the marker goes:
|
|
815
874
|
|
|
816
875
|
<!-- prettier-ignore -->
|
|
817
876
|
| `PUSH_MODE` | When | CI event fired by debug push | Marker surface | Mechanism |
|
|
818
877
|
| --- | --- | --- | --- | --- |
|
|
819
|
-
| `LOCAL` | Debug invoked on a `dev` / `main` failure, or a feature branch with no open PR | `push` event reads `head_commit.message` | **Commit message** | `bkit [verbose ci]` appended conditionally via `VERBOSE_SUFFIX=""; [ "$PUSH_MODE" = "LOCAL" ] && VERBOSE_SUFFIX=" bkit [verbose ci]"` immediately before the relevant commits in `bkit-debug.md` (Step 6 `fix`, Step 7 `soak`, Step 9 `summary`, Step 10 `close-workflow`, Step 10 `create-pr`). PR-mode runs skip the suffix (`pull_request` events ignore commit messages).
|
|
820
|
-
| `PR` | Debug invoked on a feature branch with an open PR (the dominant case) | `pull_request.synchronize` reads `pull_request.title` | **PR title** | Step 8 (Push Remediation) runs `gh pr edit --title` to idempotently append `bkit [verbose ci]` to the PR title (skip if already present) immediately before the push. Step 10 (Close Workflow) sub-step 1 strips it via `sed` + `gh pr edit` on a successful close. Failure Path / handover
|
|
878
|
+
| `LOCAL` | Debug invoked on a `dev` / `main` failure, or a feature branch with no open PR | `push` event reads `head_commit.message` | **Commit message** | `bkit [verbose ci]` appended conditionally via `VERBOSE_SUFFIX=""; [ "$PUSH_MODE" = "LOCAL" ] && VERBOSE_SUFFIX=" bkit [verbose ci]"` immediately before the relevant commits in `bkit-debug.md` (Step 6 `fix`, Step 7 `soak`, Step 9 `summary`, Step 10 `close-workflow`, Step 10 `create-pr`). PR-mode runs skip the suffix (`pull_request` events ignore commit messages). It clears itself on each push, so non-debug pushes return to the default. |
|
|
879
|
+
| `PR` | Debug invoked on a feature branch with an open PR (the dominant case) | `pull_request.synchronize` reads `pull_request.title` | **PR title** | Step 8 (Push Remediation) runs `gh pr edit --title` to idempotently append `bkit [verbose ci]` to the PR title (skip if already present) immediately before the push. Step 10 (Close Workflow) sub-step 1 strips it via `sed` + `gh pr edit` on a successful close. Failure Path / handover do not strip it, because the human investigating after the handover wants verbose CI to continue. |
|
|
821
880
|
|
|
822
|
-
Both paths idempotent
|
|
881
|
+
Both paths are idempotent: a re-run skips when the marker is present. The next debug Step 11 strip on a successful close cleans up orphan markers.
|
|
823
882
|
|
|
824
|
-
**Close PR-create decision:** the Step-1 `PUSH_MODE` does
|
|
883
|
+
**Close PR-create decision:** the Step-1 `PUSH_MODE` does not gate PR creation. Step 11 probes live PR state (`bkit prs probe --head="{BRANCH}" --base=dev`), sets `TRIGGER_PR` from `{PR_OPEN}`, adopts a mid-run PR (`bkit prs open --existing=reuse`) rather than blind-creating into the Failure Path, then the gate asserts the dispatched `pull_request` run on every feature-branch close. `PUSH_MODE` only hints where the marker goes.
|
|
825
884
|
|
|
826
|
-
**Invariant:** a successful
|
|
885
|
+
**Invariant:** a successful build / debug close leaves a PR to `dev` (created or adopted) with a run the gate asserts; the Failure Path leaves the `[skip ci]` handover + abort-guard and dispatches no CI.
|
|
827
886
|
|
|
828
|
-
**Cleanup invariant:** PR-title marker stripped on successful `/bkit-debug` close (Step 11, `PUSH_MODE = PR`). Failure Path / handover
|
|
887
|
+
**Cleanup invariant:** the PR-title marker is stripped on a successful `/bkit-debug` close (Step 11, `PUSH_MODE = PR`). Failure Path / handover keep it on purpose, because the investigator after the handover wants verbose CI to continue. The marker is cleaned up by (a) the next successful `/bkit-debug` close, (b) a manual strip, or (c) the PR merge. On merge the squash subject inherits `bkit [verbose ci]`, so one post-merge dev CI run is verbose, which is harmless recovery evidence.
|
|
829
888
|
|
|
830
|
-
**Manual override:** append `bkit [verbose ci]` to any commit message or PR title
|
|
889
|
+
**Manual override:** append `bkit [verbose ci]` to any commit message or PR title; the env block honours both. Debug's automatic propagation removes the need to do it by hand in the main case, retry evidence.
|
|
831
890
|
|
|
832
891
|
## Per-Phase Workflows
|
|
833
892
|
|
|
834
|
-
Each subsection documents command behaviour
|
|
893
|
+
Each subsection documents a command's behaviour: steps, subagents, artifacts, verdict routing and close. Agent capability and effort are in `.bkit/prompts.md`.
|
|
835
894
|
|
|
836
895
|
### `/bkit-design` — 12 steps
|
|
837
896
|
|
|
838
|
-
**Goal:** design doc only. No plan, no code.
|
|
897
|
+
**Goal:** the design doc only. No plan, no code. It always hard-stops after the summary for human review (do not invoke `/bkit-plan`).
|
|
839
898
|
|
|
840
899
|
<!-- prettier-ignore -->
|
|
841
900
|
| Step | Subagent(s) | Read | Write | Notes |
|
|
842
901
|
| --- | --- | --- | --- | --- |
|
|
843
|
-
| 1 — Start Workflow | — | tracker issue | `.lock`, tracker comment | Fetch `origin/dev`. Resolve `{ISSUE_ID}`
|
|
844
|
-
| 2 — Worktree Setup | — | repo | `.worktrees/{FID}`, `bkit.worktree.copy` files, `design-input-{RUN}.md` | `bkit worktrees setup`: create `feat/{FID}` off a freshly fetched `origin/dev` (local `dev` when it is ahead), resume it, or adopt the current branch in place; dependencies installed (install failure → **Failure Path**). `baseSha` → `runtime-resolved` row (§ Anchor Block). |
|
|
845
|
-
| 3 — Grill | — | `design-input-{RUN}.md`, newest earlier-run `design-grill-*.md` | `design-grill-{RUN}.md`, `Grill decisions` section appended to `design-input-{RUN}.md`, tracker comment (`--comment-body`) | Orchestrator interviews the human before any design work. Method adapted from Matt Pocock's `grilling` skill (MIT, https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling). Open decisions mapped as a tree; each
|
|
846
|
-
| 4 — Brainstorm & Ideate | `@bkit-design-brainstorm-ideate-1
|
|
847
|
-
| 5 — Generate Design | `@bkit-design-generate` | `design-input-{RUN}.md` (carries the `Grill decisions` section), all three brainstorms, `related-issues.md`, superseded `{YYYYMM}/{FID}-design.md` (if any) | `design-v1-draft.md` (versioned draft) | First write of deliverable design doc. Superseded design = context only, never a constraint; supplied
|
|
848
|
-
| 6 — Design Review | `@bkit-design-review-1
|
|
849
|
-
| 7 — Spike | `@bkit-design-spike`
|
|
850
|
-
| 8 — Apply Review | `@bkit-design-update` | `design-v1-draft.md`, both reviews, `design-spike.md` (if present) | `design-v2-reviewed.md` (versioned draft) | CRITICAL items always applied; OPTIONAL applied on
|
|
851
|
-
| 9 — Design Organise | `@bkit-design-organise` | `design-v2-reviewed.md` | `design-v3-organised.md` (versioned draft) | Decompose design into dependency-annotated workstreams (`WS-N`). `ORGANISE_VERDICT`
|
|
852
|
-
| 10 — Summary |
|
|
853
|
-
| 11 — Suggest
|
|
854
|
-
| 12 — Close Workflow | — | — | `{YYYYMM}/{FID}-design.md` (copy of v3), `{YYYYMM}/archive/` (superseded, re-run only) | `bkit workflows promote` (anchor stamped from the runtime-resolved base commit, any changed canonical archived, v3 copied to the canonical bucket) → `bkit workflows close --record-step --outbox --message=` (compliance grade, close row, telemetry, `chore({FID}): close-workflow` commit in the worktree) → `cd {REPO_ROOT}` → `bkit branches land` (§ Close squash). Direct: stray-artifact check (runtime pushes dev) → squash `{BRANCH}` in `.worktrees/_land-{FID}` off `origin/dev` → non-doc and canonical-blob checks → roadmap row → `docs({FID}): design DONE` commit (`--squash-of`) → `git push origin HEAD:dev`, rebuilt and retried with backoff when `dev` moved. Push refused → PR mode: roadmap commit → push → open or reuse the PR → squash-merge it, `
|
|
902
|
+
| 1 — Start Workflow | — | tracker issue | `.lock`, tracker comment | Fetch `origin/dev`. Resolve `{ISSUE_ID}` with `bkit fids parse --prompt-file` (an explicit form — `issue #N` / `issue KEY`, a tracker tag, a tracker URL into this repo / team / site, `<id>` — beats a bare `#N` / key mention; a URL elsewhere counts as neither; two distinct candidates → exit 8 → STOP, the user names the issue; no match → `bkit fids parse --branch` on a named `FID` / `feat/{FID}` branch, else issue-less: warning, issue-tied tracker calls skipped; never create; non-slug branch suffix → STOP), set label `bkit:design`, state `In Progress` (skipped issue-less). no commits on `dev` — `status.jsonl` init + `start-workflow` step entry deferred to Step 2 inside the worktree. |
|
|
903
|
+
| 2 — Worktree Setup | — | repo | `.worktrees/{FID}`, `bkit.workflows.worktree.copy` files, `design-input-{RUN}.md` | `bkit worktrees setup`: create `feat/{FID}` off a freshly fetched `origin/dev` (local `dev` when it is ahead), resume it, or adopt the current branch in place; dependencies installed (install failure → **Failure Path**). `baseSha` → `runtime-resolved` row (§ Anchor Block). |
|
|
904
|
+
| 3 — Grill | — | `design-input-{RUN}.md`, newest earlier-run `design-grill-*.md` | `design-grill-{RUN}.md`, `Grill decisions` section appended to `design-input-{RUN}.md`, tracker comment (`--comment-body`) | Orchestrator interviews the human before any design work. Method adapted from Matt Pocock's `grilling` skill (MIT, https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling). Open decisions mapped as a tree; each turn asks the whole frontier (every decision whose prerequisites are settled), numbered, each with a recommended answer worded so "yes" accepts it; plain text, no host question tool. Orchestrator looks up facts; only decisions go to the human. Decision turns stop on an empty frontier, a human stop, or `design.grill.maxTurns` - 1 turns (default 6). The last turn asked is always the draft scenario turn, counted in `maxTurns`: the orchestrator drafts the acceptance scenario (`Narrative`, `Success Criteria`, `Key Edge Cases`, `Process Sketch` — the four parts of the design's `Acceptance Scenario`) from the whole context — session prompt, issue description and comments, answers, looked-up facts — shows it in full, and asks one question per part it inferred plus a final accept question; an answer that opens new decisions returns to the decision turns while turns remain. Agreed answers → `Settled`; unanswered at stop → `Assumed, not confirmed`; "don't know" → `Open`. The draft lands under `### Draft Acceptance Scenario` behind a `DRAFT only` first line saying whether a human reviewed it; a human stop skips the draft turn and records the draft unreviewed. `bkit-design-generate` starts its `Acceptance Scenario` from the draft and records each change as a `Decisions` row, with no further confirmation item: the human reviews the scenario again at the plan's `Acceptance Scenario confirmed` box. The plan reads the design, never the draft. An earlier run's `Settled` entries stay settled and its draft is the starting draft. `grill=false` in the session prompt skips the interview; the artifact then reads `Skipped (grill=false).` `grill=true` runs it and asks the human even with `design.grill.ask` false. `ask` false, or `runtimeHeadless` = true (`bkit counters max --point=design.grill` prints `ask` false) → no question asked, no turn ended: the tree is walked taking each recommended answer as given, every new answer lands in `Assumed, not confirmed`, the draft scenario is written unreviewed, and the artifact carries a `No human interviewed this run` line. Grill assumptions stay in the design doc; ship does not ask about them. The ideate triplet, generate and both reviewers read the section through `design-input-{RUN}.md`. A `bkit-cloud.yml` `workflow_dispatch` run is headless. |
|
|
905
|
+
| 4 — Brainstorm & Ideate | `@bkit-design-brainstorm-ideate-1`, `-2`, `-3` (parallel triplet) | `design-input-{RUN}.md` | `design-brainstorm-ideate-1.md`, `-2.md`, `-3.md` | Pragmatic / optimal-tradeoff / risk-premortem lenses; effort-tier diversity (`high`/`medium`/`high`); sibling-blind. `BRAINSTORM_VERDICT` = worst of three. |
|
|
906
|
+
| 5 — Generate Design | `@bkit-design-generate` | `design-input-{RUN}.md` (carries the `Grill decisions` section), all three brainstorms, `related-issues.md`, superseded `{YYYYMM}/{FID}-design.md` (if any) | `design-v1-draft.md` (versioned draft) | First write of deliverable design doc. Superseded design = context only, never a constraint; supplied here only — not to the sibling-blind ideate triplet. |
|
|
907
|
+
| 6 — Design Review | `@bkit-design-review-1`, `@bkit-design-review-2` (parallel) | `design-v1-draft.md`, `design-input-{RUN}.md` | `design-review-1.md`, `design-review-2.md` (opinion-only logs) | Effort-tier diversity (high vs medium); sibling-blind. `REVIEW_VERDICT` = worst of two. FAIL → Failure Path. `REVIEW_SPIKE` = `Spike` header from `design-review-1.md` only. |
|
|
908
|
+
| 7 — Spike | `@bkit-design-spike` (only if `REVIEW_SPIKE` = true) | `design-v1-draft.md`, `design-review-1.md` | `design-spike.md` (opinion-only log), throwaway probes under `logs/{FID}/spike/` | Settles review-named unknowns by running code, before the design locks. `SPIKE_VERDICT` in `PASS\|CONCERNS\|FAIL` — every value continues to Step 8; the step informs, never gates. Probe files confined to `docs/plans/` (the close squash's stray guard would otherwise abort the phase five steps later). |
|
|
909
|
+
| 8 — Apply Review | `@bkit-design-update` | `design-v1-draft.md`, both reviews, `design-spike.md` (if present) | `design-v2-reviewed.md` (versioned draft) | CRITICAL items always applied; OPTIONAL applied on merit; `OUT OF SCOPE` deferred. `APPLY_VERDICT` other than PASS / CONCERNS → Failure Path. Spike evidence outranks review opinion — a FAIL claim revises the design element resting on it. |
|
|
910
|
+
| 9 — Design Organise | `@bkit-design-organise` | `design-v2-reviewed.md` | `design-v3-organised.md` (versioned draft) | Decompose design into dependency-annotated workstreams (`WS-N`), then group them into plans (`P-N`) by the deliverable test. `ORGANISE_VERDICT` other than PASS / CONCERNS (a self-verify check, such as a workstream or plan cycle, still failing after 2 fix iterations) → Failure Path. |
|
|
911
|
+
| 10 — Summary | `bkit workflows summary` | `status.jsonl` + `design-v3-organised.md` | `design-summary.md` | Commit `chore({FID}): summary bkit [skip ci]` → push. `SUMMARY_VERDICT` = FAIL → Failure Path. A spike FAIL answered by apply-review is a CONCERNS reason. |
|
|
912
|
+
| 11 — Suggest Plans | — | `design-v3-organised.md` | parent-issue comment, `status.jsonl` | `bkit plans comment` reads `## Suggested Workstreams` (none parsed → exit 3 → Failure Path) and `## Suggested Plans` (absent → one plan per workstream) and builds one advisory comment for the parent issue: one line per `P-N` (covered `WS-N` and `Requires` included); 2+ plans → the `**Parent design:**` and `**Workstreams:**` lines each plan issue carries; 1 plan → planned on the parent issue; plus the design link. `NEVER auto-trigger`. Never creates an issue, never comments on another issue, never sets blockers. |
|
|
913
|
+
| 12 — Close Workflow | — | — | `{YYYYMM}/{FID}-design.md` (copy of v3), `{YYYYMM}/archive/` (superseded, re-run only) | `bkit workflows promote` (anchor stamped from the runtime-resolved base commit, any changed canonical archived, v3 copied to the canonical bucket) → `bkit workflows close --record-step --outbox --message=` (compliance grade, close row, telemetry, `chore({FID}): close-workflow` commit in the worktree) → `cd {REPO_ROOT}` → `bkit branches land` (§ Close squash). Direct: stray-artifact check (runtime pushes dev) → squash `{BRANCH}` in `.worktrees/_land-{FID}` off `origin/dev` → non-doc and canonical-blob checks → roadmap row → `docs({FID}): design DONE` commit (`--squash-of`) → `git push origin HEAD:dev`, rebuilt and retried with backoff when `dev` moved. Push refused → PR mode: roadmap commit → push → open or reuse the PR → squash-merge it, merge `origin/dev` into the branch locally, push and retry when refused (exit 80 hands either stage to MCP; re-run with `--pr` / `--merged-sha`). Both: local `dev` fast-forward and worktree / branch removal (runtime pushes dev), landed-body scan, transport cross-check, `close-transport` row, lock release; Gate 12 reads the status row from `origin/dev` → `bkit workflows links --ref={CANONICAL_REF} --outbox` prints the close comment. Set state `In Review`; phase label `Design` persists. Final return displays `design-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, the star line, then how to silence both) as `## bkit Tips`, then offers a plain-English explanation on request. Owner answers to `Open Questions` after close (the one-by-one pass or free chat) are recorded per round: decision rows, `logs/{FID}/design-answers-{RUN}.md` (question, answer, decision key), `@bkit-design-update` editing the canonical design in place from the round's answers file, one `Owner Answers` comment on the issue per round, and a named-file commit on `dev` with no push. |
|
|
855
914
|
|
|
856
915
|
**Hard stop in Step 12 caution block:** "Design requires human review. Do not invoke `/bkit-plan`."
|
|
857
916
|
|
|
858
|
-
**Step 11 contract:** the organised design's
|
|
917
|
+
**Step 11 contract:** the organised design's `Suggested Plans` is the suggestion; a workstream is never a filed unit. Step 11 copies the plan list onto the parent issue as an advisory comment (`NEVER auto-trigger`). It does not file issues. `/bkit-plan` Step 1 parses `**Parent design:**` and `**Workstreams:**` when a human has put those markers on an issue body (a plan issue); absent → the design made on the same issue, which plan shares the FID with (`bkit fids find` resolves it); neither → standalone plan. `/bkit-build` Step 1 honours blocker edges a human has set.
|
|
918
|
+
|
|
919
|
+
### `/bkit-plan` — 8 steps
|
|
859
920
|
|
|
860
|
-
|
|
921
|
+
**Goal:** a plan at `docs/plans/{YYYYMM}/{FID}-plan.md` (canonical bucket; `{YYYYMM}` = creation month). No code, no execution. It always hard-stops after the summary for human review.
|
|
861
922
|
|
|
862
|
-
**
|
|
923
|
+
**Draft formatting in review:** Complete draft `tests plan-check` output containing only `format` / `stray` problems and no existence findings goes to the existing scope review as CRITICAL plan-edit findings. The existing plan-update pass reads the check log with the review critiques and corrects formatting while preserving the intended tasks and tests. Other draft findings retain the single generator correction and failure route. The reviewed plan and owner-answer updates must pass the full check with `--existence=refuse`; their existing single corrective update and failure routes still apply. Review round limits, test execution and other gates are unchanged.
|
|
863
924
|
|
|
864
925
|
<!-- prettier-ignore -->
|
|
865
926
|
| Step | Subagent(s) | Notes |
|
|
866
927
|
| --- | --- | --- |
|
|
867
|
-
| 1 — Start Workflow | — | Pre-flight: fetch `origin/dev`. Set label `Plan`, `In Progress`.
|
|
868
|
-
| 2 — Worktree Setup | — | `bkit worktrees setup` on `feat/{FID}` (dependencies installed; install failure → **Failure Path**); `plan-input-{RUN}.md` = session prompt +
|
|
869
|
-
| 3 — Generate Plan | `@bkit-plan-generate` | Reads `docs/templates/bkit-plan.md` (canonical plan template), `plan-input-{RUN}.md`, superseded `{YYYYMM}/{FID}-plan.md` (if any). Superseded plan = context only, never a constraint; supplied
|
|
928
|
+
| 1 — Start Workflow | — | Pre-flight: fetch `origin/dev`. Issue recovery as in design Step 1 (issue-less: tracker reads, labels and comments skipped). Set label `Plan`, `In Progress`. `bkit fids design --description-file --prompt-file` → `PARENT_FID` from a `**Parent design:**` link, **else** the feature's own `{FID}-design.md` when it exists (a design run on the same issue); **else** empty (standalone plan run on issue input alone; a change-shape issue, `.bkit/trackers.md` § Issue shapes, then supplies the Acceptance Scenario). Its `auditPaths` = every `docs/audits/{YYYYMM}/*.md` path the description and prompt name → `AUDIT_PATHS` (a named path that is not a file → exit 7 → Failure Path). no commits on `dev` — `start-workflow` step entry deferred to Step 2 inside the worktree. |
|
|
929
|
+
| 2 — Worktree Setup | — | `bkit worktrees setup` on `feat/{FID}` (dependencies installed; install failure → **Failure Path**); `bkit workflows input` writes `plan-input-{RUN}.md` = session prompt + issue text. **If** `PARENT_FID` set → also the parent design (`--design`; missing file → Failure Path). **If** `AUDIT_PATHS` set → each report in order (`--audit`; missing file → Failure Path). Standalone plans with neither skip both appends. Superseded plan is not appended here — it goes to Step 3 only. |
|
|
930
|
+
| 3 — Generate Plan | `@bkit-plan-generate` | Reads `docs/templates/bkit-plan.md` (canonical plan template), `plan-input-{RUN}.md`, superseded `{YYYYMM}/{FID}-plan.md` (if any). Superseded plan = context only, never a constraint; supplied here only — not via `plan-input-{RUN}.md`, which the Step 5 reviewers + summary also read. Audit reports in `plan-input-{RUN}.md`: **If** the input names which findings → the plan covers only those; the rest of each report is context only, not backlog. Writes `plan-v1-draft.md`: tasks in groups of task blocks (within the `bkit.workflows.tasks` caps Step 1 holds from `repo info` and passes in Context, build order). Draft still holding `PENDING` (turn cap) → a fresh `@bkit-plan-generate` fills only the `PENDING` sections and empty groups. Then `bkit tests plan-check --existence=refuse` → `plan-generate-check.md`: formatting-only findings go through review and plan-update as described above; other exit 1 findings get one targeted generator correction, then the check repeats. |
|
|
870
931
|
| 4 — Fetch Context | — | Related-issues tracker search (keyed on the generated plan's surfaces) + `bkit context ledger-scan` over `docs/{deferrals,failures}.jsonl` → `related-issues.md` (tracker-gated), `related-deferrals.md`, `related-failures.md` (each `None.` when empty). Advisory context for review; never gates, never auto-expands scope. |
|
|
871
|
-
| 5 — Review Plan | `@bkit-plan-review-1
|
|
872
|
-
| 6 — Apply Review | `@bkit-plan-update` |
|
|
873
|
-
| 7 —
|
|
874
|
-
| 8 —
|
|
875
|
-
| 9 — Check `Complexity` | `@bkit-plan-complexity-check` | `COMPLEXITY_VERDICT` ∈ {SINGLE, SPLIT}, read and recorded on the `plan-complexity-check` row as `verdict` by `steps finish --agent=bkit-plan-complexity-check` (the agent's own verdict set); exit 5 / 6 re-asks the agent. |
|
|
876
|
-
| 10 — Split Plan | `@bkit-plan-complexity-split` _(only if `split`)_ | Writes `{FID}-plan-N.md` sub-plans + `plan-split.md` log; self-verifies losslessness (`SPLIT_VERDICT` ∈ {PASS, FAIL}; FAIL → Failure Path). |
|
|
877
|
-
| 11 — Summary | `@bkit-plan-summary` | Commit `chore({FID}): summary bkit [skip ci]` → push. |
|
|
878
|
-
| 12 — Close Workflow | — | Archive any existing canonical → copy v4 → sync to `dev`, remove worktree, delete branches (same as `/bkit-design` Step 12, except `workflows promote` moves the whole `{FID}-plan*.md` set to the archive under one timestamp, copies the split's children as `{FID}-plan-{k}.md` with working names rewritten, and stamps `designPath` / `designBaseSha` into the anchor). Set state `In Review`; phase label `Plan` persists. Final return displays `plan-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, the star line, then how to silence both) as `## bkit Tips`, then offers a plain-English explanation on request. |
|
|
932
|
+
| 5 — Review Plan | `@bkit-plan-review-1`, `@bkit-plan-review-2`, `@bkit-plan-scope-check` (parallel) | One review round on `plan-v1-draft.md`; each reads the draft + the three `related-*.md` context files and writes a critique log. Review-1 reads the plan (tightness, dependency order, design coverage); review-2 reads the code (regression risk — a check current code cannot pass → CRITICAL). The scope check owns the template checks; a task missing `DONE WHEN` or `TEST FIRST` is refused by `tests plan-check`, not the scope check. Worst verdict FAIL with header `Redesign: true` (a finding needs a design change; true when any reviewer sets it) → Failure Path (§ Verdict vocabulary); any other FAIL → Step 6, then exactly one re-review of `plan-v2-reviewed.md` (round counted by `counters route --max=2`); a FAIL on that re-review → Failure Path. |
|
|
933
|
+
| 6 — Apply Review | `@bkit-plan-update` | A missing Step 5 report → back to Step 5. One pass over all three reports and `plan-generate-check.md` → `plan-v2-reviewed.md`; after the re-review, a second pass edits `plan-v2-reviewed.md` in place (`Update`, no new version); `Exempt` rows → `docs/deferrals.jsonl`, added / changed decisions → `docs/decisions.jsonl`, both via `bkit ledgers append`. Preserves every task's `DONE WHEN` field (may tighten, never remove / weaken). Then `bkit tests plan-check --existence=refuse` → `plan-update-check.md`, exit 1 → one corrective plan-update pass on only the named lines, then repeat the full check; a second exit 1 → Failure Path. Only exit 0 proceeds. `APPLY_VERDICT` other than PASS / CONCERNS → Failure Path. |
|
|
934
|
+
| 7 — Summary | `bkit workflows summary --plan={PLAN_FINAL}` | The latest `plan-review` row still `FAIL` (a resume after the first apply round) → back to Step 5 for the re-review. Copies the plan's `Acceptance Scenario` and `Open Questions` verbatim. Commit `chore({FID}): summary bkit [skip ci]` → push. |
|
|
935
|
+
| 8 — Close Workflow | — | Archive any existing canonical → copy the highest version → sync to `dev`, remove worktree, delete branches (same as `/bkit-design` Step 12, except `workflows promote` stamps `designPath` / `designBaseSha` into the anchor). Set state `In Review`; phase label `Plan` persists. Final return displays `plan-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, the star line, then how to silence both) as `## bkit Tips`, then offers a plain-English explanation on request. Owner answers to `Open Questions` after close (the one-by-one pass or free chat) are recorded per round: decision rows, `logs/{FID}/plan-answers-{RUN}.md` (question, answer, decision key), `@bkit-plan-update` editing the canonical plan in place from the round's answers file, one `Owner Answers` comment on the issue per round, and a named-file commit on `dev` with no push. |
|
|
879
936
|
|
|
880
|
-
**Hard stop in Step
|
|
937
|
+
**Hard stop in Step 8 final return:** "**HARD STOP** — do not invoke `/bkit-build`."
|
|
881
938
|
|
|
882
|
-
### `/bkit-build` —
|
|
939
|
+
### `/bkit-build` — 16 steps
|
|
883
940
|
|
|
884
|
-
**Goal:** implementation
|
|
941
|
+
**Goal:** implementation and PR creation. CI takes over once the PR exists. The workflow stops on PR creation; there is no human gate within build itself.
|
|
885
942
|
|
|
886
|
-
**
|
|
943
|
+
**Publish resolution:** `bkit status route` resolves `PUBLISH` from the `publish=true|false` session token, else from `package.json` `bkit.workflows.build.publish`: a local run reads `local`, any other run reads `remote`, and both default to `true`. `remote` accepts only `true`, so `false` there prints the advisory `bkit-build-publish-remote` and resolves `true`. A token `false` on a run that is not local is coerced to `true` with a warning. `PUBLISH` = false holds the run: no branch push, no PR, no CI and no docs sync. The worktree and branch stay, the lock is released, and the close writes `ending: held` and `publish: false`. The issue moves to `In review` with the "built locally, not published" comment, and the summary reads `Publish: held` and `Docs: not synced`. `/bkit-ship <ref>` lands a held build.
|
|
887
944
|
|
|
888
|
-
**
|
|
945
|
+
**Build never reads the CI conclusion (by design):** the Step 16 CI-Dispatch Gate proves only that a run started (`bkit runs dispatch`). `/bkit-ship` owns the result (`bkit runs gate` refuses to merge on red). A red PR → `/bkit-debug` (manual, or auto-routed by `bkit-cloud.yml`). Waiting in build would add the full CI duration to every run and race the cloud auto-router on the same branch. The final message says so.
|
|
946
|
+
|
|
947
|
+
**Group loop (Steps 7-9):** build works from one file, `docs/plans/{YYYYMM}/{FID}-plan.md`, in task-block form (`docs/templates/bkit-plan.md` § Agent Execution Runbook): groups within the `bkit.workflows.tasks` caps (§ Test-first). One pass of Steps 7-9 per group, in group order; `bkit context brief --next` picks the first group with a task neither ticked nor logged `DONE`, so a resumed run starts where the last one stopped. `VERIFY_ATTEMPT` is derived per group (`bkit counters derive --group={GROUP}`), so each group starts at 1. Between groups the unit gate runs (§ Group gate). Only verify ticks tasks; the execute log's `DONE` lines are the handover between Steps 7 and 8.
|
|
889
948
|
|
|
890
949
|
<!-- prettier-ignore -->
|
|
891
950
|
| Step | Subagent(s) | Notes |
|
|
892
951
|
| --- | --- | --- |
|
|
893
|
-
| 1 — Start Workflow | — | Pre-flight: fetch `origin/dev`. Set label `Build`, `In Progress`. Check `relations.blocked_by` — any blocker not in `{Done, Cancelled}` → Failure Path with `Blocked by {BLOCKER_ID}`. Resolve `FID`, then lock (missing month bucket → current month). no commits on `dev` — `start-workflow` step entry deferred to Step 2 inside the worktree. |
|
|
894
|
-
| 2 — Worktree Setup | — | `bkit worktrees setup` (create / resume / adopt; dependencies installed).
|
|
895
|
-
| 3 — Branch Sync | — | `bkit branches sync --merge-docs`: fetch `origin/dev`; when commits touching `docs/` are behind, merge it — ledger conflicts union, other `docs/` conflicts take `dev`, a conflict outside `docs/` aborts the merge (exit 11 → Failure Path). |
|
|
896
|
-
| 4 — Plan
|
|
897
|
-
| 5 —
|
|
898
|
-
| 6 —
|
|
899
|
-
| 7 —
|
|
900
|
-
| 8 —
|
|
901
|
-
| 9 —
|
|
902
|
-
| 10 —
|
|
903
|
-
| 11 —
|
|
904
|
-
| 12 —
|
|
905
|
-
| 13 —
|
|
906
|
-
| 14 —
|
|
907
|
-
| 15 —
|
|
908
|
-
| 16 —
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
952
|
+
| 1 — Start Workflow | — | Pre-flight: fetch `origin/dev`. Issue recovery as in design Step 1 (issue-less: tracker reads, labels, comments and the blocker check skipped). Set label `Build`, `In Progress`. Check `relations.blocked_by` — any blocker not in `{Done, Cancelled}` → Failure Path with `Blocked by {BLOCKER_ID}`. Resolve `FID`, then lock (missing month bucket → current month). no commits on `dev` — `start-workflow` step entry deferred to Step 2 inside the worktree. |
|
|
953
|
+
| 2 — Worktree Setup | — | `bkit worktrees setup` (create / resume / adopt; dependencies installed). No path moves — plan stays at canonical bucket from design close. `bkit workflows input` writes `build-input-{RUN}.md`: session prompt, issue text and the plan as it arrived — the whole plan again, so only `@bkit-build-plan-convert` reads it; it stays as the record of what the run was given. Every other build agent reads the plan or its group's brief, and run instructions in the session prompt (a redo, a resume, a constraint) reach the brief's `Deviations` section through `--note-file` (Step 7). |
|
|
954
|
+
| 3 — Branch Sync | — | `bkit branches sync --merge-docs`: fetch `origin/dev`; when commits touching `docs/` or a ledger path (`LEDGERS`, `.bkit/core/engine/commands/workflow/branches.ts`) are behind, merge it — ledger conflicts union, other `docs/` conflicts take `dev`, a conflict outside `docs/` aborts the merge (exit 11 → Failure Path). A declared `bkit:generate` script then runs on a clean tree and its output is committed as `chore({FID}): regenerate after merging dev`; a failing script → exit 25 → Failure Path. |
|
|
955
|
+
| 4 — Plan Convert | `@bkit-build-plan-convert`, run only when the plan is missing, has no task markers or is older than an issue comment | `bkit tests plan-check --existence=report` on `{FID}-plan.md` → `build-plan-check.md`. No plan (exit 2), a plan with no task markers (exit 1, problem `markers`) or with a `matrix` / `supersession` problem, or a valid plan with issue comments posted after its last commit (`newerThanPlan` > 0 from Step 2's `workflows input`) → `@bkit-build-plan-convert` writes the plan in task-block form from `build-input-{RUN}.md` and the plan file, keeping any existing plan's other sections; where they disagree the newer text wins, so later comments change the plan before any code; convert copies each `TEST EXCEPTION` an input writes word for word and never writes its own; row `build-plan-convert`, then the check re-runs. Still failing → convert once more with the printed problems, then Failure Path. Any other problem (caps, a stray `TEST FIRST` line) → Failure Path before any code, naming each problem. A valid plan with no newer comments writes a no-agent skip row (`build-plan-convert`, `--attempt=1`, comment `Status=skipped (plan already in task-block form)`) and goes to Step 5. `bkit install` / `check` / `upgrade` list each `{FID}-plan.md` with no task markers whose FID has not shipped as advisory `plan-task-markers-missing`; nothing to do by hand, this step converts it. |
|
|
956
|
+
| 5 — Plan Current | `@bkit-build-plan-current` (skipped when the mechanical trigger clears) | Orchestrator trigger `bkit branches anchor-read --field=baseSha --against=origin/dev` reads the plan's `bkit:anchor` (§ Anchor Block) and exits 12 — skipping the judgement, no agent, no artifact, its own comment naming the skip — on any of: no plan, no anchor, `baseSha` unreachable in this clone, nothing landed on `origin/dev` since it. Else it prints `value` (= `BASE_SHA`) and the agent derives its own changed-path list from it, intersects that against the paths the plan's tasks depend on, and reads per-path diffs for the intersection only. `Executable` tasks are not findings; `Reword` / `Broken` are. Judges the plan against the codebase — the design doc is not an input, and `designPath` / `designBaseSha` have no consumer here. `CURRENT_VERDICT` is advisory on every value — PASS / CONCERNS / FAIL all → Step 6; CONCERNS / FAIL are recorded, comment-posted with `Affected`, and echoed as a console advisory, never blocking. Findings carry into Step 7 as a Read for `@bkit-build-plan-tasks`; build never revises the plan, a re-run of `/bkit-plan` does. |
|
|
957
|
+
| 6 — Skills | `@bkit-build-install-skills` (skip if input contains `[skills=false]`) | If new skills installed → commit `chore({FID}): install skills bkit [skip ci]`. |
|
|
958
|
+
| 7 — Execute Plan | `@bkit-build-plan-tests`, then `@bkit-build-plan-tasks` | `bkit context brief --next` writes `build-brief-{GROUP}-{n}.md` — the group's open task blocks, the earlier tasks they depend on as context, and the plan's `Reuse Inventory` rows and `Architecture & Component Changes` entries naming the open tasks' `CREATE` / `UPDATE` / `DELETE` files (rows and entries past the 8 KB work cap are left out and counted; execute then reads the plan section) — and prints `group` (null → Step 10), `workBytes` and `workCap`. When the session prompt carries run instructions beyond naming the issue, the orchestrator writes them once to `{SESSION_DIR}/brief-note.md` and passes `--note-file`, so each brief ends with a `Deviations` section the agents apply to the tasks it names. A `build-group-start` row records the commit the group starts from, once per group. The orchestrator passes paths only; each agent reads its brief, not the plan and not `build-input-{RUN}.md`. Tests half (§ Test-first): `bkit context brief --group --tests-only --file` writes `build-brief-tests-{GROUP}-{n}.md`, the open task blocks with a planned test left, the `Derived Test Matrix` rows naming their test files, no `Reuse Inventory` or `Architecture` entries; `tests` = 0 → nothing written, the tests half is skipped. `@bkit-build-plan-tests` writes the group's planned tests and nothing else (`steps finish --step=build-plan-tests --plan` refuses a diff touching a file no `TEST FIRST` line of the group names: exit 15, `source`, one re-ask), log `build-plan-tests-{GROUP}-log.md` (`WROTE` / `PASSES` / `BLOCKED` / `SOURCE` lines). Then the orchestrator runs `bkit tests red --group` once for the group: exit 0 or 3 → code half; exit 1 → the tests agent is re-invoked once with the red report, the second red's gaps stand and reach `tests green` as `unproven`, answered once at Step 15. Code half: `@bkit-build-plan-tasks`, per group `build-plan-tasks-{GROUP}-log.md`, attempt-numbered rows (`--attempt-of=build-plan-tasks:next`), one log appended across attempts. Writes stub-first then incremental `DONE — TASK {N}` / `BLOCKED — TASK {N}` log entries via `Bash echo >>`; writes source and never a planned test case (`steps finish` exit 11, `tests` naming each planned test whose own lines changed since its red, one re-ask; other tests in the same file are free). Does not modify the plan — ticking is verify's job (per-task `Edit`-tick phase after impl is done is a known timeout vector; verify absorbs recovery). `bkit tasks open --plan= --group= --log=` names each task the plan leaves open and prints `handover`; verdict `HANDOVER` (turn cap near) or `handover` = true (a task with neither a `DONE` nor a `BLOCKED` line — the agent hit its turn cap) → Step 7 re-runs once for that group as a handover, not a failed attempt, its briefs leaving out the `DONE` tasks and the tests already proved red; the tracker comment shows `HANDOVER`; after that the verify→remediate loop (Step 8 → Step 9, bounded by `build.verify.maxAttempts`) absorbs the recovery. Else → Step 8. |
|
|
959
|
+
| 8 — Verify Plan | `@bkit-build-plan-verify` | `bkit tests green --group` first (§ Test-first) → `build-tests-green-{GROUP}-{VERIFY_ATTEMPT}.md`, read by verify and remediate; exit >= 2 → Failure Path. `bkit context diff --base=` the group's start commit → `build-diff-{GROUP}-{VERIFY_ATTEMPT}.md`, the changes since the group started. Per group, attempt-numbered: `build-plan-verify-{GROUP}-{VERIFY_ATTEMPT}.md`. Reads the group's briefs, the diff, the execute log's `DONE —` lines, `build-tests-green-{GROUP}-{VERIFY_ATTEMPT}.md` and `build-plan-current.md` (already-landed tasks). The tick is the engine's: the agent names the task numbers the codebase satisfies on the header's `Tasks` line and `bkit tasks tick --plan= --group= --tasks="<numbers>" --green=<tests-green artifact>` writes the `[x]` — a task is satisfied only when its `DONE WHEN` field is satisfied in the codebase and the green report shows no gap for it (never on a `DONE —` claim alone). `tests green` prints `verdict` and a `fixable` per gap, so the prompt keeps only its diff reads, the `Updated tests` diff check among them, and notes the `Unproven` section without a gap. Missing `DONE WHEN` on any task → FAIL (template structure broken — remediation cannot recover, routes via Failure Path). `VERIFY_VERDICT` in `PASS\|CONCERNS\|FAIL`. PASS → `bkit tests plan-check --existence=report` lists the plan's groups: exit 1 with a `matrix` / `supersession` problem → one convert retry at Step 4 sub-step 2 (still failing → Failure Path); a group numbered above `GROUP` → group gate (§ Group gate) → `build-group-gate-{GROUP}-{VERIFY_ATTEMPT}.md` + row; none → `GATE_VERDICT` = SKIPPED. `GATE_VERDICT` in `PASS\|FAIL\|SKIPPED`; PASS + gate != FAIL → Step 7. Header `Fixable` = `true` when gap-remediate can fix any gap (each `Identified Gaps Log` line ends `— Fixable: true` / `— Fixable: false`); a test a task's `TEST EXCEPTION` field names is no gap. Every non-PASS first checks the group's verify rounds against `build.verify.maxAttempts` (`counters route --point=build.verify`; used up → § Decision Pause with the loop question when `ask` is true in a session, else Failure Path). FAIL → one fixable-only Step 9 attempt (`Scope: fixable only`) when `Fixable` = `true` and a round is left, else § Decision Pause (`VERIFY_GAPS`). Group gate FAIL alone → Step 9 while a round is left; used up → the same pause when `ask` is true in a session, else Failure Path. Other CONCERNS → Step 9 while a round is left, never asked; else § Decision Pause (`VERIFY_GAPS`). Reads prior verify and remediate logs to know what was already verified. |
|
|
960
|
+
| 9 — Remediate Gaps | `@bkit-build-plan-gaps-remediate` (only if Step 8 CONCERNS, group gate FAIL, or the fixable-only attempt) | The verify header's `Loosened` line (`VERIFY_LOOSENED`) not `none` → no fixer this round: `@bkit-build-plan-tests` restores each named test (removed or loosened expectations back as at `base`, additions kept, a `WROTE` log line), `steps finish --step=build-plan-tests` commits it, `tests red --group` records it again, Step 8 re-runs. Else attempt-numbered: `build-plan-gaps-remediate-{GROUP}-{VERIFY_ATTEMPT}-log.md`; reads the group's briefs for its task blocks. Group gate FAIL → Context hands the agent the group gate command (`tests run`, log `{OUTBOX}/build-plan-gaps-remediate-{GROUP}-{VERIFY_ATTEMPT}-gate.log`): it re-runs it after each fix until exit 0, treats each newly exposed failure as a gap of the same round, sweeps for other tests built on the same failing assumption, and logs `DONE — Group gate: exit 0` (or `BLOCKED — Group gate`); `PASS` needs that line. Prompt-enforced only: Step 8's re-run is the check. Stub-first artifact + flat append-only log (`DONE —` per gap fixed; `BLOCKED —` per blocked gap, appended via `Bash echo >>`); reads glob of own prior attempts to skip already-fixed gaps. Header `Fixed` = gaps with `DONE` this attempt. Resumed into this step (a `retry` decision) → the group's last verify round is read back first: `VERIFY_ATTEMPT` (`counters derive --position=current`), `VERIFY_VERDICT` and the group gate's verdict (`status route`), the gate counted SKIPPED when that round wrote no gate log. No progress — `bkit branches scan-diff --base=HEAD~1 --code` exit 1 (nothing changed outside `docs/plans`, `docs/*.jsonl`, `.bkit/*.jsonl`: only logs and ledgers), or `Fixed` = 0 → § Decision Pause; verify never re-runs on unchanged code. Else re-run Step 8 (its next row is the next `VERIFY_ATTEMPT`). Over `build.verify.maxAttempts` → Failure Path. |
|
|
961
|
+
| 10 — Holistic Verification | `@bkit-build-plan-verify` (holistic mode) | Once per run, after the last group: every group of the plan plus cross-group integration, cross-checked against every group's execute log; writes `build-plan-verify-holistic.md`. The agent names the satisfied task numbers per group on the header's `Tasks` line and the workflow ticks them — one `bkit tasks tick --plan= --group= --tasks="<numbers>"` call per task group; the agent edits no plan. A row already recorded (challenge fix groups coming back through the loop) → Step 11 without re-running. FAIL → Failure Path. |
|
|
962
|
+
| 11 — Build Challenge | `@bkit-build-challenge-2`, plus `@bkit-build-challenge-1` on a large change (parallel) | At most `build.challenge.maxAttempts` rounds (`CHALLENGE_MAX`, `counters max --point=build.challenge`; `challenge merge --round` refuses a round over it, exit 2 → Failure Path): `CHALLENGE_DONE` (`bkit status resume` `challengeDone`, the last round already merged) → Step 12 without reviewing again. `bkit challenge gate` fetches `origin dev` (offline → the last fetch, logged), then sizes `origin/dev...HEAD`, on every pass (`docs/plans/**` excluded): under 300 lines and 10 files is small → the security reviewer (`-2`) runs alone and the finish and merge drop challenge-1's artifact and report; else both run. Each reviewer reads the same `tmp/bkit-diff-{FID}.md`, written just before (§ Diff per reader); on `partial diff coverage` challenge-2 runs a targeted `git diff` on each omitted file touching a security-relevant path. Reviewers read the plan and the diff only. Each writes every finding as one task block under `Findings Log` (`build-challenge-1.md`, `build-challenge-2.md`): severity, class, `Fixable`, `Location`, `DONE WHEN`, and a `TEST FIRST` for every finding. `bkit challenge merge --plan={FID}-plan.md` then appends the `CRITICAL\|HIGH\|MEDIUM` findings to the plan as task blocks stamped `**Round:** N`, in new last groups of <= `bkit.workflows.tasks.maxPerGroup` tasks, plus one `Derived Test Matrix` row per appended task's test when the plan carries the table; a finding at the `Location` and severity of an earlier challenge task that is still open reopens that task instead (its `**Round:**` line gains the round, e.g. `1, 2`; listed in `reopened` and `fixTasks`), one already done in an earlier round gets a new task; writes each `LOW` one as a `docs/deferrals.jsonl` row (`reason` `low-severity`), drops findings a `build-decision-*.md` item accepted, and prints the route: `none` → Step 12; `fix` (every task fixable, in any round) → Step 7, whose brief takes the first new group, `CHALLENGE_ROUND` + 1 before the last round, `CHALLENGE_DONE` = true in it; `pause` (a `**Fixable:** false` task, or more findings than one merge takes, which writes nothing) → § Decision Pause. A re-run on the same reports appends nothing. Exit 22 (a report not in task-block form) or exit 23 (the findings fail `plan-check`: a missing `TEST FIRST`, a test cap passed; `problems` printed) → reviewers re-run once with the reason in their Context, then Failure Path. Resumed into an open challenge Decision Pause → the limit read (`CHALLENGE_MAX`) and sub-steps 2 and 5 run again (the merge finds its tasks in the plan, writes nothing and prints the round's open tasks as `fixTasks`) → back to the pause's question. The challenge row carries the `round` it ran as (`--field=round=`); `bkit status resume` reads it back as `challengeRound` — one more once a challenge's merge wrote tasks (its next row is `build-plan-tasks` or `build-decision`, not `build-run-tests`), at most `CHALLENGE_MAX`; `challengeDone` = true once a last-round challenge row has a route row after it. |
|
|
963
|
+
| 12 — Run Tests | — | `bkit tests run` runs the deepest `bkit:gate:*` the consumer declares — descending `static-unit-integration`, `static-unit` (§ Local gate scripts) — and saves the full output to `{OUTBOX}/run-tests-{TEST_ATTEMPT}.log`; `--artifact` writes a copy clamped with `debug-evidence` to `docs/plans/{YYYYMM}/logs/{FID}/run-tests-{TEST_ATTEMPT}.md`, which rides the step's commit (row `artifacts` + `clamped`), so the log survives the worktree. `.md`, not `.log`: `*.log` is gitignored. Exit 3 (no gate declared) / 4 (gate could not run, 126 / 127) → Failure Path, never a FAIL verdict. Pre-PR: no E2E (CI covers it on the resulting PR). Build does not run the live tier — the @live boundary needs a deployed URL, so it is validated post-merge by the push-only `bkit-tests-live` CI canary and reproduced on demand via `/bkit-debug`; build gates on local tiers only and records no `testsLiveSkipped` (out of build's scope by design, not skipped). A repo gating unit branch-coverage puts `test:coverage:unit` in `bkit:lane:unit`, so this gate and the CI unit lane run the same `package.json` script (one source for the threshold) and a coverage regression fails in the worktree here instead of only on the PR. `TEST_VERDICT` = PASS → Step 15. FAIL with a round left under `build.tests.maxAttempts` → `counters progress --check=build-run-tests --fix=build-failure-remediate`: `trend` `stuck` or `worse` → § Decision Pause (`TESTS_LOOP`: Stop / Try again), else Step 13 without asking; none left → § Decision Pause (`TESTS_LOOP`) when `ask` is true in a session, else Failure Path. |
|
|
964
|
+
| 13 — Diagnose Failure | `@bkit-debug-failure-diagnose` (only if Step 12 FAIL) | Reads the committed Step 12 test log `docs/plans/{YYYYMM}/logs/{FID}/run-tests-{TEST_ATTEMPT}.md`. Writes `build-failure-diagnose-{TEST_ATTEMPT}.md`. Resumed into Steps 13-14 → `TEST_ATTEMPT` is read back (`counters derive --step=build-run-tests --position=current`). |
|
|
965
|
+
| 14 — Remediate Failure | `@bkit-debug-failure-remediate` (only if Step 12 FAIL) | Gets the diagnosis's `Strategy` in its Context (`status route --step=build-failure-diagnose` `strategy`). Writes `build-failure-remediate-{TEST_ATTEMPT}-log.md`. Stub-first artifact + flat append-only log (`DONE —` per fix step; `BLOCKED —` per blocked step, appended via `Bash echo >>`). No skip-done — each attempt is diagnosis-driven and may pick a different strategy. Re-run Step 12 (its next row is the next `TEST_ATTEMPT`). |
|
|
966
|
+
| 15 — Summary | `bkit workflows summary` | Unticked plan tasks, or no plan file (`No plan file`) → FAIL. A group's execute or gaps-fix FAIL answered by that group's later non-FAIL verify, or a challenge FAIL answered by its fix tasks or a Decision Pause, is a CONCERNS reason. Commit `chore({FID}): summary` → open-PR probe → push (`-u origin {BRANCH}`). PR already open (resumed build) → push would fire CI + cloud auto-router on a branch build is still writing → probe stops run first (same probe as Step 16). `bkit-cloud.yml` backstop: no-op while build runs (`.bkit/cloud.md` § Branch-aware routing). |
|
|
967
|
+
| 16 — Close Workflow & Create PR | — | `bkit:auto` re-read before close-workflow commit; open-PR probe; `bkit branches scan-diff --base=origin/dev --paths='(^\|/)(migrations\|migrate)/'` (case-insensitive, any depth — covers Supabase, Prisma, Drizzle, Rails) → `FORCE_BUILD`. `bkit prs open` (base pinned `dev`; body = the `bkit:issue` / `bkit:fid` marker + plan path; retries the create once; reads the base back → exit 6 when it is not `dev`, guarding repos whose default base is `main`); exit 80 → `create_pull_request` with the printed `title` / `body` / `base` / `head`. `FORCE_BUILD` → `bkit branches force-build --open-pr=<n>` after the PR opens: ` bkit [force build]` into the PR title (`gh pr edit`; exit 80 → `update_pull_request`, re-run `--title-set`), then an empty `chore({FID}): force build bkit [force build]` commit (auto-route suffix from `--label`) pushed — its `synchronize` event starts the run that reads the new title. Never amends; an `engine-action` row skips the commit on a re-run. Then CI-Dispatch Gate (`bkit runs dispatch`). Set state `In Review`; phase label `Build` persists. Worktree persists for follow-up `/bkit-debug` or `/bkit-ship`. Final return displays `build-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, the star line, then how to silence both) as `## bkit Tips`, then offers a plain-English explanation on request. |
|
|
968
|
+
|
|
969
|
+
**Failure Path includes handover:** when exhausted retry counts trigger it, it invokes `@bkit-debug-abort-handover` and posts the `Workflow Handover` comment.
|
|
970
|
+
|
|
971
|
+
#### Decision Pause
|
|
972
|
+
|
|
973
|
+
One mechanism for every build question: verify gaps logged `Fixable: false`, a no-progress Step 9 attempt, challenge tasks no agent can fix (`**Fixable:** false`) or more findings than one merge takes, a failed test round after a round that made no progress, a used-up verify or tests limit in a session, and the planned tests still unproven at Step 15. A used-up limit asks, and a go-on answer grants that loop one more allowance (§ Ask points).
|
|
974
|
+
|
|
975
|
+
- **Record:** `bkit decisions compose` writes `build-decision-{RUN}-{K}.md` from the orchestrator's items JSON: `Status: OPEN`, the header (`Question` (`VERIFY_GAPS|CHALLENGE|TESTS_LOOP|UNPROVEN`), `From` (`verify` / `challenge` / `tests` / `summary`), `Pause step`, `Group` (verify), `Verify attempt` or `Test attempt`, `Plan`), the `{workflow} {point}: attempt {n} of {max}` line and `## Progress` block for loop questions (`--loop`), then one item per question in the question layout (§ Ask points). Status ends `DECIDED`, or `ASSUMED` while an assumed accept is in it.
|
|
976
|
+
- **Who asks:**
|
|
977
|
+
- **If** `ask` is true and the run is not headless → the orchestrator asks, in session. Never a subagent, because subagents cannot reach the human.
|
|
978
|
+
- **If** `ask` is false or the run is headless → `bkit decisions apply --by=headless` takes each recommendation. Exit 4 means hard blockers are left: in a session only those are asked; headless, the run takes the Failure Path.
|
|
979
|
+
- **Unproven tests (Step 15):** before the summary, `bkit tests green` over the whole plan lists each planned test still `unproven` (never failed before its code existed). One pause, `Question: UNPROVEN`, one item per test, options `Accept` / `Stop`, recommended `Accept`; asked once per run (a decision file with `Question: UNPROVEN` already there skips it). Headless → `Accept (assumed)`, which ship asks the owner to confirm. Route `summary` → Step 15.
|
|
980
|
+
- **Hard blockers:** the unfixable gaps (`no-test-first`, `test-first-malformed`, `test-first-unread`, `exception-refused`) and `**Fixable:** false` challenge findings. No recommendation; "yes" never answers one.
|
|
981
|
+
- **Accept** by the owner: written ONLY after explicit human approval of that item. Agents NEVER write one on their own judgement. An `exception-refused` gap or an `UNPROVEN` item → a `**TEST EXCEPTION:**` field in the task's block, committed alone (`git commit -- {plan}`) so `tests green` honours them; each entry ends `— {reason} (owner, {YYYY-MM-DD})`, and the field replaces the task's existing one, never a second, so the plan-alone commit always changes its lines and blame points at it; other → `docs/decisions.jsonl` row (`by.step` `build-decision`, `rationale` `accepted by owner: …`). Verify and `bkit challenge merge` read `build-decision-*.md` and drop accepted items. An accepted challenge task is also ticked `[x]` and its title ends ` — accepted by owner`, so the summary does not count it as unfinished. Group-gate failures are never items.
|
|
982
|
+
- **Accept (assumed):** taken without the owner — `Decision: Accept (assumed) — {reason} ({ask:false|headless}, {RUNTIME}, {date})`. Settled for this build (verify, `acceptedLocations()`, gaps-remediate treat it as accepted), but it is not an acceptance: no `docs/decisions.jsonl` row, no `TEST EXCEPTION`. The build summary lists each one and keeps the verdict at CONCERNS; `/bkit-ship` asks the owner to confirm it (§ `/bkit-ship`, Confirm Assumed Items).
|
|
983
|
+
- **Fix now:** a new task block with `DONE WHEN` + `TEST FIRST` and one `Derived Test Matrix` row per test in it, numbered above the plan's highest task. From verify: inside the paused group when it stays within `bkit.workflows.tasks.maxPerGroup` tasks and `bkit.workflows.tasks.maxTestsPerGroup` tests, else a new group straight after it, every later group renumbered. From tests or challenge: a new last group. The pause writes no test or fix code: Step 7 writes each test with `@bkit-build-plan-tests`, records its red with `tests red`, and only then writes the fix with `@bkit-build-plan-tasks`. Then `tests plan-check` (non-zero → Failure Path) → Step 7, whose brief picks the group holding the open task → Step 8 → onward. Fix now on a challenge task reuses that task as it stands, and a challenge-originated fix reaches the challenge reviewers again through Steps 10-11. Taken without asking → `Decision: Fix now — recommended; applied without asking ({RUNTIME})`.
|
|
984
|
+
- **Try again** (loop questions only): one more fix round on the same problems; the items wait undecided. `From: verify` → Step 9, `From: tests` → Step 13. The round counts against the same limit. A verify pause at its used-up limit asks the loop question too (`--loop=verify`), in a session only.
|
|
985
|
+
- **Allowance:** every route but Stop from a verify or tests pause runs `counters grant` for that loop; it writes a row only when the limit is used up and `ask` is true.
|
|
986
|
+
- **Then:** `steps finish --step=build-decision --field=route={fix|retry|verify|tests|summary} --comment-body` (decision posted to the tracker) → Step 7 (`fix`), Step 9 (`retry` after a verify or group-gate loop) or Step 13 (`retry` after a tests loop), re-run Step 8 (`verify`), Step 12 (`tests`), or Step 15 (`summary`). The row's `route` is what `bkit status resume` reads to resume after a decision: `retry` resumes at Step 9 (`build-plan-gaps-remediate`) when the paused step was `build-plan-verify` or `build-group-gate`, at Step 13 (`build-failure-diagnose`) when it was `build-run-tests`. A challenge decision with a fix to run → `fix`; one already in the last round also sets `CHALLENGE_DONE`, so Step 11 goes on to Step 12.
|
|
987
|
+
- **Fixer reads the answer:** Step 9 (`@bkit-build-plan-gaps-remediate`) and Step 13 (`@bkit-debug-failure-diagnose`) read the newest `build-decision-{RUN}-*.md`, so the owner's words reach the next round. Every subagent learns an owner's answer only from the decision file in its `Read`, never from a paraphrase in its `Context` (the build's **Owner decisions** contract line). The `STANDARD → PIVOT → FINAL` ladder reads every run and is not reset by a decision: each further round moves up a rung, `FINAL` stays `FINAL`.
|
|
988
|
+
- **Stop:** the owner says stop → decision file → `build-handover.md` → `workflows handover --push` (comment posted) → lock released → STOP with the run still `IN_PROGRESS`; no `workflows fail`, no `bkit:failed`. Next `/bkit-build` resumes at the open decision file and asks. The handover writes `owner-pause` too, so the wait until the resume counts as one owner stop; the resume's own `owner-pause` joins that open stop.
|
|
989
|
+
|
|
990
|
+
#### Ask points
|
|
991
|
+
|
|
992
|
+
Every point where a run can ask the owner has two settings under `package.json` `bkit.workflows.<workflow>.<point>`: `ask` (true: stop and ask; false: carry on with the recommendation) and a hard limit. Install fills missing keys; a bad value falls back to its default with the advisory `bkit-ask-settings-invalid` (`bkit check`).
|
|
993
|
+
|
|
994
|
+
<!-- prettier-ignore -->
|
|
995
|
+
| Point | Default | Counts | Asks |
|
|
996
|
+
| --- | --- | --- | --- |
|
|
997
|
+
| `design.grill` | `{ "ask": true, "maxTurns": 6 }` | Interview turns, the draft acceptance turn included | Each turn's questions (§ `/bkit-design`, Grill) |
|
|
998
|
+
| `build.verify` | `{ "ask": true, "maxAttempts": 2 }` | Verify rounds per group | Every gap item: unfixable, unchanged by a fix round, or left after the last round |
|
|
999
|
+
| `build.challenge` | `{ "ask": true, "maxAttempts": 2 }` | Challenge rounds | Every finding item |
|
|
1000
|
+
| `build.tests` | `{ "ask": true, "maxAttempts": 2 }` | Test rounds | Loop question before a further fix round, only when `counters progress` `trend` is `stuck` or `worse` |
|
|
1001
|
+
| `debug.fix` | `{ "ask": true, "maxAttempts": 2 }` | Remediate rows across every debug run of the feature | `Q1 — Fix: … Stop here instead of another fix attempt?`, only when `trend` is `stuck` or `worse` |
|
|
1002
|
+
| `debug.soak` | `{ "ask": true, "maxAttempts": 2 }` | Soak rows across every debug run of the feature | `Q1 — Soak: …` before the first and each further soak attempt, only when `trend` is `stuck` or `worse` |
|
|
1003
|
+
| `ship.merge` | `{ "ask": true, "maxAttempts": 2 }` | Failed arrivals at Step 10: gate refusals plus failed merges | `Q1 — Merge: …` before a fix round, only when the diagnosis verdict is not `PASS` |
|
|
1004
|
+
|
|
1005
|
+
- **A used-up limit asks:** with `ask` true and not headless, a used-up `build.verify`, `build.tests`, `debug.soak` or `ship.merge` limit goes to a question, never straight to the Failure Path (debug fix → SOAK first). The owner's go-on answer (`Fix now`, `Try again`, or `Accept` at a verify pause) runs `bkit counters grant`, which appends one `allowance-granted` row: that loop alone, and that group alone for verify, gets one more full allowance of `maxAttempts`. The limit becomes `maxAttempts x (1 + grants)`, read by `counters route` / `counters max` (`grants`, `allowance`) and by `challenge merge --round`; once the new allowance is used up too, the run asks again. `grant` refuses below the limit (`below-limit`) or with `ask` false (`ask-off`), exit 1, nothing written. `ask` false or headless → a used-up limit goes to the Failure Path. A question never resets a count. `build.challenge` never fails at its limit: the last round's fixes are not challenged again.
|
|
1006
|
+
- **Limits are fixed for the run:** `workflows start` copies the workflow's own points into the `workflow-started` row's `limits`. `counters route --point= --file= --workflow=` reads that copy and prints `limitsFrom` = `run`; a run with no copy for the point reads `package.json` (`limitsFrom` = `package.json`). `counters max --point= --file= --workflow=` reads the same copy; without `--file` it reads `package.json`. A step commit never changes them: `steps finish` with `--commit=auto` refuses when `package.json` `bkit.workflows` differs from `HEAD` → exit 13, nothing written, `changed` names each dotted key. In a shared checkout a `package.json` already dirty when the run started is not the step's: the commit leaves it out, so it is not checked.
|
|
1007
|
+
- **Headless** (`runtimeHeadless` true, GitHub Actions only) behaves as `ask: false` at every point. `bkit counters route` and `counters max` print `ask` already false when headless.
|
|
1008
|
+
- **`ask: false`:** loop questions take the recommendation; `Fix now` is applied; `Accept` is recorded as assumed. Hard blockers are still asked in a session and go to the Failure Path headless.
|
|
1009
|
+
- **Question layout**, every point: the `{workflow} {point}: attempt {n} of {max}` line (loop questions; `turn` for the grill), then per question `**Q{n} — {title}:** {question}`, `Options: A) … / B) …`, and `Recommended: A) X — {reason}` or `No recommendation — {why}`, each title and question stating what the owner must decide and what each option does, in plain English, before naming any file, test or identifier; then `Reply per question. "yes" takes every recommendation. "stop" writes a handover; the run can be resumed.` Option names: `Try again` / `Decide` / `Stop`, `Accept` / `Fix now`, `Confirm` / `Reject`. Each step routing on the owner's answer reads a lettered reply (`B`, `B)`, `B) {option}`) as the option it labels; `parseDecisionItems` reads a `Decision:` line the same way (`optionAnswer`).
|
|
1010
|
+
- **Progress report:** `bkit counters progress --check=<step> --fix=<step>` (and `decisions compose --loop`) → the `## Progress` block of a loop question. Counted from `status.jsonl` and git, never judged by an agent:
|
|
1011
|
+
|
|
1012
|
+
<!-- prettier-ignore -->
|
|
1013
|
+
| Field | Source |
|
|
1014
|
+
| --- | --- |
|
|
1015
|
+
| `counts` (`5 → 2`) | `failures` on each check row |
|
|
1016
|
+
| `codeChanged` | `git diff` of source (plan logs and ledgers excluded) between the first and last check rows' `parentSha`; `null` when git cannot compare |
|
|
1017
|
+
| `lastStrategy` / `nextStrategy` / `finalSpent` | fix rows' `strategy`; next rung from every run |
|
|
1018
|
+
| `minutesPerRound` | check-row timestamps |
|
|
1019
|
+
| `trend` | `worse` = count rose; `closing` = count fell and code changed (or unknown); `stuck` = otherwise; `first-round` = one check row |
|
|
1020
|
+
| `recommend` | `try-again` when `closing`, else `stop`; `null` on `first-round` |
|
|
1021
|
+
|
|
1022
|
+
- **Loop question:** `Q1`, worded so "yes" accepts `recommend`: `Another fix round?` (`Try again`) on `try-again`, else `Decide the items below instead of another fix round?` (`Decide`) when items exist, else `Stop`; items numbered from `Q2`. Every route into the pause sets `PAUSE_QUESTION` — `VERIFY_GAPS` for unfixable gaps, a fix round that changed nothing, or no round left; `TESTS_LOOP` for a failed test round with rounds left and `trend` `stuck` or `worse`; `CHALLENGE` for challenge tasks no agent can fix, or more findings than one merge takes. It picks the header, the items and the loop question, and resume reads it back from the `Question:` header.
|
|
913
1023
|
|
|
914
1024
|
### `/bkit-debug` — 11 steps
|
|
915
1025
|
|
|
916
|
-
**Goal:** diagnose and remediate failing test or CI run
|
|
1026
|
+
**Goal:** diagnose and remediate a failing test or CI run, and push the fix back to the adopted branch. With `[repro]`, write a failing test before remediation, including when CI already supplies the failure.
|
|
1027
|
+
|
|
1028
|
+
**Evidence selection (Steps 1–2):** parse the named existing branch with `branches parse --workflow=debug`, then adopt it with `worktrees setup --branch` when supplied. Resolve prompt, current human issue text and active status with `runs locate`, validating branch and commit ancestry. Exit 0 selects red CI; exit 1 selects local discovery only after an explicit local choice or a proven no-red result. Exit 80 enters the mapped read fallback and revalidates its normalized evidence; ambiguous or unavailable references and branch conflicts stop before tests or edits. `status meta --ci-selection-file` persists the validated selection atomically and `status route` rederives gates. Resolution runs before downstream resume; a changed `ciGeneration` returns to Step 3 and requires fresh context.
|
|
917
1029
|
|
|
918
|
-
**
|
|
1030
|
+
**Selected CI loop:** Step 3 passes saved `--ci-run` / `--ci-url`, records `source: ci` and `ciGeneration`, and does not run a local discovery gate until a matching-generation DONE remediation or soak row exists. Local rounds keep their clamp records; CI evidence rounds have no local clamp. Step 4 requires freshly checked complete selected-run logs with the matching identity receipt; partial or unavailable evidence stops diagnosis. `[repro]` routes to Step 5 once per generation: YES proceeds directly to Diagnose or Soak; NO blocks resolution. Steps 5–8 carry the selected identity and stamp their rows with `ciGeneration`. At close, every branch, including `main` without a PR, requires the configured gate and selected workflow to pass at the exact head held from the final successful push or dispatch. A missing pushed head stops before success. Original and verifying run links stay separate in the comment and final report. A red, skipped, cancelled, absent or unavailable verification blocks success.
|
|
919
1031
|
|
|
920
|
-
**
|
|
1032
|
+
**Evidence round contract:** `tests run` writes a CI artifact with `Verdict: FAIL`, `Source: ci`, repository, workflow, run, attempt, commit, URL and generation. Its row has `source: ci`, `scope: ci:<runId>`, and null gate, exit code and failure count; it explicitly says the local gate did not run. `steps finish` checks this artifact against the active selection instead of demanding a local clamp record. `status route` returns `ciRun`, `ciGeneration`, `ciFixDone` and `ciReproduced`; only DONE rows for the current generation count. The reproduction row persists the report's `Reproduced` value as `reproduced`. After a matching fix, ordered declared gates cover known failed tiers first, retain the normal fallback order, and honor `[live=off]`. The configured workflow selector remains `package.json` `bkit.testing.ciWorkflow`; selecting another workflow adds its final proof rather than replacing the configured gate.
|
|
921
1033
|
|
|
922
|
-
**
|
|
1034
|
+
**Mode detection (Step 1):** `bkit prs probe` (any base): open PR → `PUSH_MODE` = PR, else LOCAL (exit 80 → `list_pull_requests`); Step 11 re-probes and re-records it, so labels and the ` bkit [verbose ci]` suffix on the close follow a PR opened or closed mid-run; one `bkit status route --workflow=debug --fid= --month= --prompt-file={SESSION_DIR}/prompt.md` prints `debugAttempt` (which debug run this is; a resume keeps its number), `debugMode`, `repro` and `gates`. `debugMode` (NORMAL | SOAK), first match wins: `[soak]` in session prompt → SOAK; the newest run still `IN_PROGRESS` (a resume) is already in SOAK — `debug-failure-soak` rows, or `debugMode` SOAK in its `workflow-meta` (a Step 3 escalation) → SOAK; `debug-failure-remediate` rows across every debug run of the feature >= `debug.fix.maxAttempts` → SOAK; else NORMAL. A finished run's mode never carries into the next run; its fix and soak rows count against the limits. `repro` = `[repro]` in session prompt; `gates` = debug's candidates, the live one dropped on `[live=off]` in session prompt. The issue body is not read for markers. A cause that cannot be localised → SOAK is judged by the Step-6 diagnose `Mode: SOAK`, not here.
|
|
923
1035
|
|
|
924
|
-
**
|
|
1036
|
+
**Ladder + cutover:** `NORMAL` (diagnose + remediate) and `SOAK` (accumulating-context instrument-or-fix). There is no observe mode; `[DEBUG-OBSERVE]` appears only in the soak agent loop. SOAK entry: invocation start (fix attempts used up across the feature's runs, or `[soak]`); mid-run Step-6 `Mode: SOAK` (`Verdict` != PASS); `FIX_ATTEMPT` over `debug.fix.maxAttempts` (STANDARD → PIVOT → FINAL) — final SOAK escalation before handover. `bkit status meta --debug-mode=SOAK` records the switch; `SOAK_ATTEMPT` counts soak rows across every debug run of the feature against `debug.soak.maxAttempts` — nothing resets it (default worst case without asking: 2 fix + 2 soak attempts per feature, over 1 to 4 runs). With `debug.fix.ask` / `debug.soak.ask` true and not headless, the Loop Question asks before each further attempt (`Try again` / `Stop`; Stop → handover, run stays `IN_PROGRESS`). Used-up soak attempts with `debug.soak.ask` true in a session → the Loop Question too; `Try again` grants one more allowance of soak attempts (§ Ask points). SOAK is terminal: the switch is one-way. Soak loops on whatever Run Tests fails on (live or mocked). Diagnose recommends; the orchestrator decides.
|
|
925
1037
|
|
|
926
|
-
**
|
|
1038
|
+
**Test round identity:** Step 3 derives `NORMAL_ATTEMPT` with `counters derive --position=next` before running tests and uses it for both the test-run row and completion. `DEBUG_ATTEMPT` remains the workflow run number and names its context artifacts. Every executed local gate emits `source: local`; its clamp record uses `NORMAL_ATTEMPT`.
|
|
1039
|
+
|
|
1040
|
+
**Verification provenance:** The additional selected-workflow gate accepts only runs whose repository and head repository match the saved repository, whose branch and commit match the verification target, and whose event matches `--event` when supplied. A missing head-repository identity or a fork result cannot establish success.
|
|
1041
|
+
|
|
1042
|
+
**Local discovery loop:** Step 3 Run Tests (head; iter 1 = reproduce) → FAIL with budget → Step 4 Fetch Context → fix step (`NORMAL` → Diagnose 6 + Remediate 7; `SOAK` → Soak 8) → loop Step 3. PASS after fix → Push 9 → Summary 10 → Close 11; PASS no fix → can't-reproduce → Summary (CONCERNS); with `REPRO` → Fetch Context 4 → Reproduce 5: reproduced → test committed → loop Step 3 (records the red; a PASS there with no fix → Summary (CONCERNS)); not reproduced → test changes removed → Summary (CONCERNS). Soak loops only on a failing Run Tests, never a green suite. Reproduce run spends one `NORMAL_ATTEMPT`. Fix attempts used up → SOAK; soak attempts used up → Failure Path. Close asserts no `[DEBUG-OBSERVE]` survives debug diff (no-leak) before CI push.
|
|
1043
|
+
|
|
1044
|
+
**Live tier (Step 3):** appends the declared `test:integration:live` / `test:e2e:live` / `test:live` unless `[live=off]`, recorded verbatim in `scope`. No live tier → CONCERNS + `testsLiveSkipped` at close, never a silent pass. To learn whether live ran, read `scope` after the fact.
|
|
1045
|
+
|
|
1046
|
+
**Context fetch (Step 4):** once per failing round and before Reproduce. `context list-blocks` enumerates consumer blocks below `bkit:end`; temporary scripts run through `context fetch --ci-selection-file`. Blocks share no mutable state. Selected CI supplies exact identity pins and requires a matching complete receipt plus nonempty logs; missing, partial or unavailable selected evidence blocks diagnosis. Unpinned blocks discover their own sources and keep their skip breadcrumbs. Artifacts are fenced and clamped as `context-<context>-<name>-{DEBUG_ATTEMPT}.md`; flat JSON rows may become tables. Step 3's artifact records either selected CI evidence or actual local output, and tests are not rerun here. Coverage and outcomes are narrated per block; `context finalise` records configured contexts, artifacts, clamp records and the active CI generation. The related-issues search remains advisory.
|
|
1047
|
+
|
|
1048
|
+
The following table describes the local discovery route and shared step mechanics. The selected CI loop above replaces its local discovery and reproduction routes.
|
|
927
1049
|
|
|
928
1050
|
<!-- prettier-ignore -->
|
|
929
1051
|
| Step | Subagent(s) | Notes |
|
|
930
1052
|
| --- | --- | --- |
|
|
931
|
-
| 1 — Start Workflow | — | Pre-flight: `bkit repo info --fetch`. `bkit issues labels --phase=debug`: sets `bkit:debug`, drops the prior phase label, `next:*` and `bkit:failed`; state `In Progress`. PR-mode: `PR_NUMBER` → `PUSH_MODE
|
|
932
|
-
| 2 — Worktree Setup | — |
|
|
933
|
-
| 3 — Run Tests | — | **
|
|
934
|
-
| 4 — Fetch Context | — |
|
|
935
|
-
| 5 — Failure Reproduce | `@bkit-debug-failure-reproduce`
|
|
936
|
-
| 6 — Failure Diagnose | `@bkit-debug-failure-diagnose`
|
|
937
|
-
| 7 — Failure Remediate | `@bkit-debug-failure-remediate`
|
|
938
|
-
| 8 — Failure Remediate Soak | `@bkit-debug-failure-soak`
|
|
939
|
-
| 9 — Push Remediation | — |
|
|
940
|
-
| 10 — Summary |
|
|
941
|
-
| 11 — Close Workflow | — | A live `prs probe --head` (any base; skipped on `dev` / `main`) sets `{PR_OPEN}` and re-records `PUSH_MODE` (`bkit status meta --push-mode`); labels, the subject suffix, the title strip and `TRIGGER_PR` all key on it, not on the Step-1 value. No-leak assertion: fails the run if any added `[DEBUG-OBSERVE]` line survives the debug diff (`
|
|
942
|
-
|
|
943
|
-
**Failure Path** includes conditional handover via `@bkit-debug-abort-handover` when max-retry exhausted → `debug-handover.md`. PR
|
|
1053
|
+
| 1 — Start Workflow | — | Pre-flight: `bkit repo info --fetch`. Issue recovery as in design Step 1 (issue-less: tracker reads, labels and comments skipped). `bkit issues labels --phase=debug`: sets `bkit:debug`, drops the prior phase label, `next:*` and `bkit:failed`; state `In Progress`. PR-mode: `PR_NUMBER` → `PUSH_MODE`; on `dev` / `main` no `prs probe`, `PUSH_MODE` = LOCAL. `DEBUG_ATTEMPT` + `DEBUG_MODE` per Mode detection above. No commits on `dev`: the `start-workflow` step entry waits for Step 2, inside the worktree. |
|
|
1054
|
+
| 2 — Worktree Setup | — | Debug creates no branch. An explicit `--branch` safely adopts the named existing branch; otherwise resume `.worktrees/{FID}`, adopt an existing `feat/{FID}`, or adopt the current branch in place. `main` is ineligible. Another feature's in-place run blocks adoption. Hold `startSha` as `DIFF_BASE`, or `origin/dev` when null. Write the debug input and persist the attempt, modes and validated evidence selection before downstream resume. |
|
|
1055
|
+
| 3 — Run Tests | — | **Loop head (both modes).** `NORMAL_ATTEMPT` = this row's `attempt` (`steps done --attempt=next`). `bkit tests run` runs the deepest `bkit:gate:*` the consumer declares — descending `static-unit-integration-e2e-live`, `static-unit-integration-e2e`, `static-unit-integration`, `static-unit`; `[live=off]` drops the live candidate (§ Local gate scripts). Iteration 1 = reproduce. Records `verdict` + `failures` + `scope` (the gate script name; ends `:live` only when the live gate ran); writes the status row but does not commit it — a `chore(...)` HEAD here would let a preview host's `^chore:` ignore rule cancel the preview and demote CI to a partial tier, skipping the suites the loop is proving; `parentSha` advances transitively through Steps 4-7. PASS routes on active-run rows, not the attempt count: a fix step ran (`debug-failure-remediate` / `debug-failure-soak`, one `counters route --of=<step>,<step>:count`) → Step 9; Failure Reproduce ran, no fix since (reproduce tests passed on the re-run — intermittent) → Step 10 (CONCERNS); neither + `REPRO` → Step 4; neither → Step 10; FAIL + NORMAL + `FIX_ATTEMPT` (`counters route --of=debug-failure-remediate:next --all-runs --point=debug.fix`) within the limit → Loop Question (from the second attempt; asks only when `counters progress` `trend` is `stuck` or `worse`) → Step 4; FAIL + NORMAL + used up → `bkit status meta --debug-mode=SOAK` → the SOAK check; FAIL + SOAK + `SOAK_ATTEMPT` (`--of=debug-failure-soak:next --all-runs --point=debug.soak`) within the limit → Loop Question → Step 4; used up with `debug.soak.ask` true in a session → Loop Question (`LOOP_LIMIT`) → Step 4; else → Failure Path. |
|
|
1056
|
+
| 4 — Fetch Context | — | (on FAIL with budget, or before Reproduce) Mode-agnostic. Every consumer `context-fetch` block (`bkit context list-blocks` → `fetch`, fenced + clamped) + a related-issues tracker search → per-context `context-*-{DEBUG_ATTEMPT}.md` written only when content exists; `bkit context finalise` → `FETCH_VERDICT`, `contextsConfigured`, `clamped`. Routes: PASS → Step 5; SOAK → Step 8; else → Step 6. |
|
|
1057
|
+
| 5 — Failure Reproduce | `@bkit-debug-failure-reproduce` (only if `REPRO` and first Run Tests PASS) | Writes `debug-failure-reproduce-{NORMAL_ATTEMPT}.md` + tests failing on the reported symptoms (`Mode: SOAK` → they repeat the scenario until they fail reliably); no implementation changes. `steps finish` commits `test({FID}): reproduce reported failure`, holds `Reproduced`. `YES` → Step 3 (its FAIL row = the red; its PASS row with no fix since → Step 10); `NO` → test changes removed → Step 10. |
|
|
1058
|
+
| 6 — Failure Diagnose | `@bkit-debug-failure-diagnose` (only if `DEBUG_MODE` = NORMAL) | `STRATEGY` STANDARD → PIVOT → FINAL by prior diagnose. Writes `debug-failure-diagnose-{NORMAL_ATTEMPT}.md`; when a live tier failed on a functional assertion, anchors on that real-boundary ground truth (treats infra / credential failures as environment, not feature-broken). Sets `Mode` (NORMAL / SOAK) — `SOAK` when the cause is not localisable (gated on `Verdict` != PASS); in `NORMAL` the orchestrator then records the switch (`status meta --debug-mode=SOAK`) and fast-tracks to Step 8 (Soak), else → Step 7. |
|
|
1059
|
+
| 7 — Failure Remediate | `@bkit-debug-failure-remediate` (only if `DEBUG_MODE` = NORMAL) | Gets the diagnosis's `Strategy` in its Context (`status route --step=debug-failure-diagnose` `strategy`). Writes `debug-failure-remediate-{NORMAL_ATTEMPT}-log.md` + source files. Orchestrator commits `fix({FID}): {description}{VERBOSE_SUFFIX}` (`{description}` from the first `DONE — Step` line, truncated to 72 chars; `VERBOSE_SUFFIX = " bkit [verbose ci]"` iff `PUSH_MODE = LOCAL`); the fix commit is the HEAD the next Run Tests / Push pushes. → loop to Step 3. |
|
|
1060
|
+
| 8 — Failure Remediate Soak | `@bkit-debug-failure-soak` (only if `DEBUG_MODE` = SOAK) | `SOAK_ATTEMPT` = soak rows across every debug run of the feature + 1 (`--count-field=soakAttempt=debug-failure-soak:next:all`). One accumulating context (reads its prior `debug-failure-soak-*-log.md`) applies the single next instrument-or-fix step against the failing boundary (the real model/DB/stream behind a live tier when one ran, else the failing tier the run surfaced); adds `[DEBUG-OBSERVE]` scaffolding and strips every marker before any declared fix (no-leak); commits `fix({FID}): soak {description}`. → loop to Step 3. Bounded by `debug.soak.maxAttempts`, counted across the feature's debug runs. |
|
|
1061
|
+
| 9 — Push Remediation | — | (PASS after a fix) Status file-only (no intermediate commit so Step 7/8's `fix(...)` stays HEAD at push). PR-mode: append `bkit [verbose ci]` to PR title if absent. Push (skipped on `dev`: the Step 11 close pushes). → Step 10. |
|
|
1062
|
+
| 10 — Summary | `bkit workflows summary` | Commit `chore({FID}): summary{VERBOSE_SUFFIX}` → push (skipped on `dev`). `SUMMARY_VERDICT` = PASS / CONCERNS → Step 11; FAIL → Failure Path. |
|
|
1063
|
+
| 11 — Close Workflow | — | A live `prs probe --head` (any base; skipped on `dev` / `main`) sets `{PR_OPEN}` and re-records `PUSH_MODE` (`bkit status meta --push-mode`); labels, the subject suffix, the title strip and `TRIGGER_PR` all key on it, not on the Step-1 value. No-leak assertion: fails the run if any added `[DEBUG-OBSERVE]` line survives the debug diff (`bkit branches scan-diff --base={DIFF_BASE} --marker="[DEBUG-OBSERVE]" --expect-none`, exit 1 on a hit: added lines of `{DIFF_BASE}...HEAD`, excluding `docs/plans/`) before the CI-triggering push — diff-scoped, not a tree-wide `git grep`, so the bkit-managed prompt / command files that quote the literal marker never false-trip (the soak agent's own `git grep '[DEBUG-OBSERVE]'` self-check in `bkit-debug-failure-soak.md` is the first layer). Else Failure Path. PR open: strip `bkit [verbose ci]` from PR title. Commit `chore({FID}): close-workflow{VERBOSE_SUFFIX}` → push + (LOCAL, no PR) `chore({FID}): create-pr{VERBOSE_SUFFIX}` (`VERBOSE_SUFFIX = " bkit [verbose ci]"` iff `PUSH_MODE = LOCAL`) via `bkit branches push --commit= --label=` (one per run, `engine-action` row). Auto-route marker `bkit [auto route]` on the CI-triggering HEAD when `bkit:auto`. Records `testsLiveSkipped` when no live tier ran (no `test:...:live` task in `scope`). Set state `In Review`; phase label `Debug` persists. Worktree persists. On `dev` the close pushes through `bkit branches push --mode=dev --require-ci` (the run's own commits; the pushed `sha` is `{DEV_SHA}` and the close is recorded against it), then `runs dispatch --sha`, `runs wait --until=completed` and `runs gate --capstone-only` on that sha run before `locks release`; `skipped: no-run-commits` (every run commit already on `origin/dev`) → narrated, no CI run gated, lock released; a red run, a refused push or a replay conflict → Failure Path naming the run. The handover path runs via Failure Path. Final return displays `debug-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, the star line, then how to silence both) as `## bkit Tips`, then offers a plain-English explanation on request. |
|
|
1064
|
+
|
|
1065
|
+
**Failure Path** includes a conditional handover via `@bkit-debug-abort-handover` when max-retry is exhausted → `debug-handover.md`. In PR mode `bkit [verbose ci]` is kept (not stripped), because the investigator wants verbose CI to continue (§ `bkit [verbose ci]` Marker Propagation, cleanup invariant).
|
|
944
1066
|
|
|
945
1067
|
### `/bkit-ship` — 14 steps
|
|
946
1068
|
|
|
947
|
-
**Goal:** verify PR, land docs and bookkeeping on it, merge to `dev`, clean up worktree.
|
|
1069
|
+
**Goal:** verify the PR, land docs and bookkeeping on it, merge to `dev`, and clean up the worktree. Staging is path-scoped via `bkit ledgers commit` (frozen allow-list). `BOOK_ROOT` = `{WORKTREE_PATH}` resolves the single tree every status write targets. `{OUTBOX}` (`.bkit/cli.md`) survives the Step 14 worktree removal.
|
|
948
1070
|
|
|
949
|
-
**Summary is displayed verbatim before the Failure Path.** A FAIL summary's `Recommended Next Step` is the only handoff that reaches a human on that route
|
|
1071
|
+
**Summary is displayed verbatim before the Failure Path.** A FAIL summary's `Recommended Next Step` is the only handoff that reaches a human on that route, because the Close Workflow step's final return is unreachable once the run enters the Failure Path. All five phase workflows carry it.
|
|
950
1072
|
|
|
951
1073
|
**One `git push` per standalone push step.** The permission layer reads the whole command string, so an unexecuted `--force-with-lease` arm in a `case`/`||` chain makes a plain push read as a force-push and the call is refused. Carried in the `Git:` caution bullet of all five phase workflows.
|
|
952
1074
|
|
|
953
|
-
**`ship-merged-on-entry` marks the resume route.** Sub-step 8 is skipped when the PR is already MERGED, so without the row an auditor cannot separate that route from a run that dropped `ship-worktree-setup` / `ship-regression-guard` rows.
|
|
1075
|
+
**`ship-merged-on-entry` marks the resume route.** Sub-step 8 is skipped when the PR is already MERGED, so without the row an auditor cannot separate that route from a run that dropped `ship-worktree-setup` / `ship-regression-guard` rows. The route goes to Step 13: Steps 3-12 ride or merge the PR, and a merged PR carries nothing more. On a resume after a crash past the merge, the docs are already on `dev`. When the PR was merged by hand before ship, there is no docs sync and no summary.
|
|
954
1076
|
|
|
955
|
-
**Gate asserts carry `--branch`.** The gate's head-keyed run query is filtered server-side, so a moved head returns an empty list whether CI never ran or ran at a superseded SHA; only a second, branch-scoped query separates exit 14 from exit 10. Ship passes `--file={STATUS}` so an override audit row lands in the run's own `BOOK_ROOT` log
|
|
1077
|
+
**Gate asserts carry `--branch`.** The gate's head-keyed run query is filtered server-side, so a moved head returns an empty list whether CI never ran or ran at a superseded SHA; only a second, branch-scoped query separates exit 14 from exit 10. Ship passes `--file={STATUS}` so an override audit row lands in the run's own `BOOK_ROOT` log. When the file is absent or unwritable, the row goes to stderr, so it is never invisible.
|
|
956
1078
|
|
|
957
1079
|
**Docs and bookkeeping ride the PR (Steps 5-8):**
|
|
958
1080
|
|
|
959
1081
|
- Sweep → docs sync + summary → skill prune → one `--scope=pr` `[skip ci]` commit → plain push to `{SHIP_BRANCH}`; all in the feature worktree, before the merge. The merge carries docs, logs, ledgers, the `SHIPPED` row (`$WT/.bkit/issues.jsonl`) and skill removals to `dev`.
|
|
960
1082
|
- Pre-merge, every ship write has a publish channel on every runtime: post-merge, a cloud runtime cannot push `dev`, and the merge's `--delete-branch` removes the only branch it can.
|
|
961
|
-
-
|
|
962
|
-
- Summary FAIL stops the merge. `@bkit-ship-update-docs` reads `git log origin/dev..HEAD` against the unmerged branch
|
|
1083
|
+
- Pre-merge pushes to `{SHIP_BRANCH}` happen only in these steps, none forced: opening a missing PR (Step 2), the Path B merge push (Step 4), Commit + Push Bookkeeping (Step 8), the regenerate round (Step 10) and a Failure Remediate fix (Step 12) (`.bkit/core/engine/audits/workflows/ship-invariants.test.ts`).
|
|
1084
|
+
- A Summary FAIL stops the merge. `@bkit-ship-update-docs` reads `git log origin/dev..HEAD` against the unmerged branch, so it sees the shipped commits. `ship-deferred-sweep.md` rides the same commit.
|
|
963
1085
|
|
|
964
1086
|
**Validated-head carry-forward (Step 9 + gate `--validated`):**
|
|
965
1087
|
|
|
966
|
-
- `CODE_HEAD` = head before the bookkeeping commit. `VALIDATED_HEAD` = `CODE_HEAD` while the PR head is `CODE_HEAD` plus bookkeeping only (`bkit ledgers only-bookkeeping`,
|
|
967
|
-
-
|
|
1088
|
+
- `CODE_HEAD` = head before the bookkeeping commit. `VALIDATED_HEAD` = `CODE_HEAD` while the PR head is `CODE_HEAD` plus bookkeeping only (`bkit ledgers only-bookkeeping`, on the `--scope=pr` allow-list below); else the PR head.
|
|
1089
|
+
- The `--scope=pr` allow-list is the frozen list, top-level `docs/*.md` and the globs in the repo's `bkit.testing.ciSkipPaths`. A repo lists in `ciSkipPaths` the project docs it keeps outside `docs/`, such as a `CHANGELOG.md`. The globs work as in `bkit.testing.minPushPaths` (`.bkit/templates.md` § Git hooks — Husky), and install seeds `[]`. The engine names no such file itself, and a glob that matches nothing selects nothing.
|
|
1090
|
+
- This is the one definition of ship's bookkeeping. Ship's Step 8 commit, `bkit ledgers only-bookkeeping`, the merge gate's carry-forward, `bkit ci min-push` and the pre-push hook's `bkit ci bookkeeping-push` all read it, so ship's `[skip ci]` bookkeeping push reaches the open PR.
|
|
1091
|
+
- CI is awaited only when `VALIDATED_HEAD` != `ENTRY_HEAD`, or on gate-refusal re-entry, so a PR that arrives green costs zero extra runs. Path B pays one run: the Step 4 merge of `origin/dev` moves the head, and Step 9 dispatches CI at the merged head, so a clash between the branch and newer `dev` commits surfaces as a red PR before the merge, not as a red `dev` push run after it.
|
|
1092
|
+
- GitHub's `mergeable` can be wrong on large diffs, and it ignores `merge=union`, so ship never reads it: Step 4 merges locally, and a merge GitHub still refuses goes through Steps 11-12 like any refused merge.
|
|
968
1093
|
- `bkit runs gate --head=<PR head> --validated=<VALIDATED_HEAD> --month= --fid=` re-checks the relation itself (non-bookkeeping change or non-ancestor → code 17), then runs every check at the validated SHA. `--match-head-commit <PR head>` still pins what merges.
|
|
969
|
-
-
|
|
970
|
-
- `dev`
|
|
1094
|
+
- The bookkeeping commit merges untested. `lint-staged` formats it at commit, and post-merge `dev` CI (`ship-merge-ci` row) is the backstop.
|
|
1095
|
+
- When `dev` requires status checks (classic protection or ruleset), GitHub refuses a head with no run, so Step 9 probes both and validates at the PR head.
|
|
971
1096
|
|
|
972
1097
|
**Close Workflow records the merge-CI verdict and publishes on every runtime:**
|
|
973
1098
|
|
|
974
|
-
- `ship-merge-ci` row (verdict + reason) written before
|
|
1099
|
+
- The `ship-merge-ci` row (verdict + reason) is written before a red result routes to **Failure Path**. A red merge is recorded, never inferred from a missing close row.
|
|
975
1100
|
- Close commit built in a throwaway `.worktrees/_land-{FID}` off `origin/dev` (book's logs copied, ledgers via `bkit ledgers union`) → push `dev`; `dev` moved → rebuilt, pushed again; refused → `ship-close/{FID}` PR, squash subject `[skip ci]`; a PR GitHub refuses to merge stays open for a human, worktree kept.
|
|
976
|
-
-
|
|
1101
|
+
- The feature worktree and `{SHIP_BRANCH}` are removed only once the close is on `dev`, because the book lives there until then.
|
|
977
1102
|
- `bkit ledgers union` never carries `.bkit/issues.jsonl`: the `SHIPPED` row is pre-merge, so unioning it into `dev` after a pre-merge failure would mark an unmerged feature shipped.
|
|
978
1103
|
|
|
979
|
-
**Tier-1 carrier:** `bkit runs gate` + `bkit ledgers` + the `TIMEOUTS` table (`commands/workflow/runs.test.ts`, `commands/workflow/ledgers.test.ts`, `.bkit/core/engine/shared/timeouts.test.ts`). **Tier-2 carrier:** `.bkit/core/engine/audits/workflows/ship-invariants.test.ts` (no `git add -A`, `bkit ledgers` staging, `BOOK_ROOT` status writes, `--match-head-commit`, canonical 14 step keys, pre-merge pushes confined to
|
|
1104
|
+
**Tier-1 carrier:** `bkit runs gate` + `bkit ledgers` + the `TIMEOUTS` table (`commands/workflow/runs.test.ts`, `commands/workflow/ledgers.test.ts`, `.bkit/core/engine/shared/timeouts.test.ts`). **Tier-2 carrier:** `.bkit/core/engine/audits/workflows/ship-invariants.test.ts` (no `git add -A`, `bkit ledgers` staging, `BOOK_ROOT` status writes, `--match-head-commit`, canonical 14 step keys, pre-merge pushes confined to Step 2 PR open + Step 4 merge push + Commit + Push Bookkeeping, none forced, no hand-written `dev` checkout or push, `.deferred-blocked` writer under `BOOK_ROOT`). **Tier-3 carrier:** detector corpus.
|
|
980
1105
|
|
|
981
1106
|
<!-- prettier-ignore -->
|
|
982
1107
|
| Step | Subagent(s) | Notes |
|
|
983
1108
|
| --- | --- | --- |
|
|
984
|
-
| 1 — Start Workflow | — | Resolve `FID
|
|
985
|
-
| 2 — Verify PR (Worktree Setup + Regression Guard) | — | `ship-input-{RUN}.md` in the worktree (includes the plan when there is one). `bkit prs probe --head={SHIP_BRANCH} --state=all` → `PR_NUMBER`, `ENTRY_HEAD
|
|
986
|
-
|
|
|
987
|
-
|
|
|
988
|
-
|
|
|
989
|
-
|
|
|
1109
|
+
| 1 — Start Workflow | — | Resolve `FID` (issue recovery as in design Step 1; issue-less: tracker reads, labels and comments skipped); `bkit runtime detect` → `RUNTIME_WORKTREES`; `bkit locks acquire` (main checkout; missing month bucket → current UTC month); straight after the lock, before any tracker write, `bkit worktrees setup --workflow=ship [--branch=] [--issue=]` resolves `SHIP_BRANCH` (see Branch eligibility), creates / resumes (no rebase) / adopts, writes the `.worktree-owned` marker to the outbox only for a worktree it created, and prints `branchWarning`; in the worktree `bkit status path` → `BOOK_ROOT`, `bkit workflows start --branch={SHIP_BRANCH}` refuses a checkout on another branch (exit 15, before any row), clears the stale `.deferred-blocked` / `.rebase-failed` sentinels and opens the run (its log lives in the worktree), `bkit runtime row` — so every later failure has a book to keep its record in; create `{OUTBOX}`; preflight `actions: write` once; set label `Ship`, `In Progress`. no commits on `dev`. |
|
|
1110
|
+
| 2 — Verify PR (Worktree Setup + Regression Guard) | — | `ship-input-{RUN}.md` in the worktree (includes the plan when there is one). `bkit prs probe --head={SHIP_BRANCH} --state=all` → `PR_NUMBER`, `ENTRY_HEAD`. No PR → `bkit branches push --mode=plain --set-upstream --ahead-of=origin/dev` (feature branch only, never forced; nothing ahead or on `dev` / `main` → exit 21 `Nothing to ship` → Failure Path), `bkit prs open --file={STATUS} --workflow=ship` into `dev` (an `engine-action` row makes a re-run reuse the PR, never open a second; `workflow-meta` `openedPr:true`), wait for its CI, `bkit prs checks` (not green → Failure Path). Already MERGED → `ship-merged-on-entry` → Step 13. Regression guard: `bkit runs wait --pr= --until=present` (no CI run for PR HEAD → FAIL), then `--until=completed`. |
|
|
1111
|
+
| Confirm Assumed Items | — | `bkit decisions pending` lists the build's `Decision: Accept (assumed)` items nobody confirmed. In a session (never headless; `ship.merge.ask` does not apply) the orchestrator asks `Confirm` / `Reject` per item; `bkit decisions apply --by=owner` writes the answer (confirm → the real acceptance, a `docs/decisions.jsonl` row). Then `pending --defer` writes one `needs-decision` deferral per item still unconfirmed, and ship carries on and merges; `bkit workflows summary` adds a `## Ship Completed with Assumed Items` heading listing them. |
|
|
1112
|
+
| 3 — Base Check | — | `bkit branches sync --head=<ENTRY_HEAD>` → `basePath`: A (`origin/dev` is an ancestor) → Step 5; B → Step 4. Path A runs no `bkit:generate` and pushes nothing: CI fails on a stale generated file (`CI_GENERATED_FLOOR` plus `bkit.testing.ciGenerated`), and Step 10's regenerate round runs only when every failed CI step is one of those. |
|
|
1113
|
+
| 4 — Integrate (Path B only) | `@bkit-ship-conflict-resolve` (exit 24 only) | `bkit branches sync --merge --fid= --file={STATUS} --sentinel=` merges `origin/dev` into `SHIP_BRANCH` locally: it commits the run's uncommitted work first (`chore({FID}): carry uncommitted work before merging dev`), merges (`chore({FID}): merge dev`), unions the append-only ledgers, takes a conflicted lockfile from `dev` and regenerates it, takes a conflicted generated register from `dev` with the branch's edit to its hand-written region, takes a conflicted embedding doc's generated block from `dev` and merges the rest of that doc, merges a conflicted install record entry by entry with `dev`'s value where both sides changed an entry, then rebuilds the register and commits it, runs a declared `bkit:generate` and commits its output, and records an `engine-action` `merge` row. `outcome` merged → `bkit branches push --mode=plain` → Step 5; `current` (`dev` has not moved since Step 3) → Step 5; exit 24 (`pending`: conflicts outside the ledgers, lockfile, generated register, embedding docs and install record, merge left in progress) → `@bkit-ship-conflict-resolve` resolves them by hand and re-runs the block, which commits the merge: PASS → plain push → Step 5, FAIL → `git merge --abort` → Failure Path; any other exit → the block aborted the merge and wrote `.rebase-failed` → Failure Path. GitHub's `mergeable` is never read, because it ignores `merge=union`. |
|
|
1114
|
+
| 5 — Deferred Sweep | `@bkit-ship-deferred-sweep` | `bkit branches fast-forward --onto=origin/{SHIP_BRANCH}` (fetch failed → exit 10, diverged → exit 22; both → Failure Path). No `{FID}-plan.md` → warning: every build writes one, so the branch was not built by `/bkit-build`. Two engine verbs settle the sweep's mechanical facts: `bkit branches scan-diff --disabled-tests --base=origin/dev` (exit 1 → its `disabled` list holds each hit's `file:line` and test name → `Blocking Deferrals` → FAIL) and `bkit ledgers triage --fid= --plan=` (applies the deferral tests, writes each `unjustified` / `TRIAGED` row, prints each row's `key`, `bucket` and test result). `@bkit-ship-deferred-sweep`: PASS → Step 6; FAIL touches `$BOOK_ROOT/.../logs/{FID}/.deferred-blocked` → Failure Path (merge never happens). First pass only — gate-refusal re-entry lands at Step 9. |
|
|
1115
|
+
| 6 — Update Docs & Summary | `@bkit-ship-update-docs`, then `bkit workflows summary --pr={PR_NUMBER}` | `bkit context ledger-scan --terms={FID} --source=docs/deferrals.jsonl --artifact={OUTBOX}/ship-pending-items.md` writes the deferral scan the docs agent fills `Pending Items` from — the agent reads that artifact, never `docs/deferrals.jsonl`, and writes no ledger row. `update-docs` runs in `{WORKTREE_PATH}`, writes `ship-update-docs.md` + edits cataloged docs. Then `bkit roadmap feature --root=$WT` appends the `SHIPPED` row and folds the board — `DOCS_VERDICT` requires it appended with `status` = `SHIPPED`. The summary writes `ship-summary.md` with the PR's size from `gh pr view` (line dropped when `gh` fails). Summary FAIL → Failure Path before any merge. |
|
|
990
1116
|
| 7 — Prune Skills | — | `bkit skills prune` in the worktree: uninstalls every non-`bkit-*` skill `.agents/skills.md` does not list (whole-name match). Warns and carries on: a missing registry skips the prune, a failed uninstall is listed in `failed`. Reconciles the union of on-disk `.agents/skills/` directories and `skills-lock.json` keys — a disk-only scan strands lock entries whose directory was removed out-of-band. |
|
|
991
|
-
| 8 — Commit + Push Bookkeeping | — | Record `CODE_HEAD`; `ship-bookkeeping-push` row first; one `bkit ledgers commit --scope=pr` commit `docs({FID}): ship bookkeeping bkit [skip ci]` (docs, FID logs, ledgers, skill removals);
|
|
992
|
-
| 9 — Re-validate | — | Resolve `VALIDATED_HEAD` (carry-forward above). Wait only when `VALIDATED_HEAD` != `ENTRY_HEAD` **or** `REVALIDATE_REASON` = `gate-refusal`: `bkit runs wait --head=<VALIDATED_HEAD> --until=present --dispatch-if-absent` (6 polls; `gh workflow run {bkit.ciWorkflow}` only on no-run, then `VALIDATED_HEAD` = PR head) → `ship-revalidate-dispatch` row → head-anchored `--until=completed` (`SHIP_CI_WAIT_TIMEOUT_S`; budget exhausted → `ship-revalidate-timeout` row → Failure Path) → Step 10. |
|
|
993
|
-
| 10 — Merge Gate + Merge PR | — | `bkit runs gate --pr= --validated=<VALIDATED_HEAD> --branch= --file= --snapshot={OUTBOX}/pre-merge-snapshot.jsonl --record={STATUS}` — the
|
|
994
|
-
| 11 — Failure Diagnose | `@bkit-debug-failure-diagnose`
|
|
995
|
-
| 12 — Failure Remediate | `@bkit-debug-failure-remediate`
|
|
1117
|
+
| 8 — Commit + Push Bookkeeping | — | Record `CODE_HEAD`; `ship-bookkeeping-push` row first; one `bkit ledgers commit --scope=pr` commit `docs({FID}): ship bookkeeping bkit [skip ci]` (docs, FID logs, ledgers, skill removals; refuses on `dev`, `main` or a detached HEAD, exit 12); `bkit branches push --mode=plain` to `{SHIP_BRANCH}` only when `outcome` = committed — an unconditional push would start a CI run on every ship. |
|
|
1118
|
+
| 9 — Re-validate | — | Resolve `VALIDATED_HEAD` (carry-forward above). Wait only when `VALIDATED_HEAD` != `ENTRY_HEAD` **or** `REVALIDATE_REASON` = `gate-refusal`: `bkit runs wait --head=<VALIDATED_HEAD> --until=present --dispatch-if-absent` (6 polls; `gh workflow run {bkit.testing.ciWorkflow}` only on no-run, then `VALIDATED_HEAD` = PR head) → `ship-revalidate-dispatch` row → head-anchored `--until=completed` (`SHIP_CI_WAIT_TIMEOUT_S`; budget exhausted → `ship-revalidate-timeout` row → Failure Path) → Step 10. |
|
|
1119
|
+
| 10 — Merge Gate + Merge PR | — | `bkit runs gate --pr= --validated=<VALIDATED_HEAD> --branch= --fetch --file= --snapshot={OUTBOX}/pre-merge-snapshot.jsonl --record={STATUS}` — the only merge precondition: the snapshot (PR head, `VALIDATED_HEAD`, dev SHA, ancestor, capstone run, mergeable) is written before it decides, a skip token in the PR title refuses (18), a refusal is recorded as `ship-gate-refusal`. `bkit prs merge --match-head=<gate mergeHead> --delete-branch {LABEL_FLAGS} --expect-merged` (empty body). `state` = MERGED → Step 13. `prs merge` refuses a non-`dev` base (exit 8, nothing merged → Failure Path); the exit 80 MCP route asserts `base.ref` = `dev` before `merge_pull_request`. `ISSUE_ID` empty → no label re-read, `{LABEL_FLAGS}` empty. Non-zero gate: 10/11/14/17 → bounded Step 9 (poll only; `bkit counters route --name=MERGE_ATTEMPT --of=ship-merge-pr:count --rows=ship-gate-refusal:count --point=ship.merge` counts failed merges plus gate refusals); 12 with `regenerable` = true → the regenerate round (below); else Failure Path. **Regenerate round:** on exit 12 the gate reads the run's jobs and prints `failedSteps`, each failed step outside the capstone as `{job}/{step}` (`{job}/` for a job that failed with no failed step), and `regenerable` = true when every one is on `CI_GENERATED_FLOOR` (`bkit-tests-static/Check Capability Register`, `bkit-tests-static/Run bkit Check`) plus `bkit.testing.ciGenerated`. The engine decides, never a model: one failed step off the list makes the whole result a Failure Path, because fixing half of it still leaves CI red. The round takes the same `ship.merge` count without asking → `bkit branches regenerate --attempt={MERGE_ROUNDS}` commits only what `bkit:generate` changed as `fix({FID}): regenerate attempt {N}` → `CODE_HEAD` = its `head` → plain push → Step 9 re-validates at that head. `unchanged` (regenerating fixes none of the failed steps), `undeclared` or a failing `bkit:generate` → Failure Path. CI's re-run is the only re-check: a local one would need a local command per list entry. Non-merged: `bkit counters route --point=ship.merge` (failed merges plus gate refusals) → Step 11, asked before the Step 12 fix round when `ship.merge.ask`, or Failure Path. |
|
|
1120
|
+
| 11 — Failure Diagnose | `@bkit-debug-failure-diagnose` (only if not merged) | Writes `ship-failure-diagnose-{MERGE_ATTEMPT}.md`. |
|
|
1121
|
+
| 12 — Failure Remediate | `@bkit-debug-failure-remediate` (only if not merged) | Writes `ship-failure-remediate-{MERGE_ATTEMPT}-log.md`. `Strategy` ladder (`STANDARD → PIVOT → FINAL`). PASS → `bkit ledgers commit --scope=full --stage-tracked-updates` commits the fix as `fix({FID}): failure-remediate attempt {MERGE_ATTEMPT}` (no skip token, so CI runs), `bkit branches push --mode=plain` pushes it unforced (ship never forces), → Step 9, which re-validates CI at the new head, then Step 10 re-merges. Resumed after the remediate row (`after` = `ship-failure-remediate`) → sub-step 4 with `verdict` = PASS; `MERGE_ATTEMPT` not held → read back first with `counters derive --step=ship-merge-pr --position=current`. FAIL → Failure Path: its handover sends code-level failures back to build, since a source-file retry loop would re-merge identical remote content. |
|
|
996
1122
|
| 13 — Update Local Dev | — | `bkit branches sync-dev`: fetch + fast-forward local `dev` to `origin/dev`, no checkout (`merge --ff-only` + frozen install when the main checkout is on `dev` and `dev` moved; install failure → exit 16 → **Failure Path**). Local-only `dev` commits → logged with the publish command, never pushed; step still passes. Step key `ship-switch-to-dev`. |
|
|
997
|
-
| 14 — Close Workflow | — | `bkit runs gate --squash-of=<PR> --capstone-only --record={STATUS}` → records `ship-merge-ci`, then refuses unless the capstone passed at the squash commit. The capstone job's result alone decides: the run's conclusion and other jobs (deploys, notifications) never fail the close of a merged PR. `bkit workflows close --flush --pr-number= --squash-sha= --outbox= --token=` grades compliance, records `ship-close-workflow`, writes telemetry in the worktree, lands the single path-scoped `[skip ci]` close commit on `dev` via the throwaway checkout (refused → `ship-close/{FID}` PR)
|
|
1123
|
+
| 14 — Close Workflow | — | `bkit runs gate --squash-of=<PR> --capstone-only --record={STATUS}` → records `ship-merge-ci`, then refuses unless the capstone passed at the squash commit. The capstone job's result alone decides: the run's conclusion and other jobs (deploys, notifications) never fail the close of a merged PR. `bkit workflows close --flush --pr-number= --squash-sha= --outbox= --token=` grades compliance, records `ship-close-workflow`, writes telemetry in the worktree, lands the single path-scoped `[skip ci]` close commit on `dev` via the throwaway checkout (refused → `ship-close/{FID}` PR) — a close that did not land keeps the lock and exits non-zero for the Failure Path; once on `dev`, `--branch={SHIP_BRANCH}` removes a workflow-created worktree only (`.worktree-owned` marker in the outbox), prunes, deletes local + remote branch (a worktree holding it blocks both → `branchBlockedBy`; `dev` / `main` refused); then the lock is released; step returns to `REPO_ROOT`. Gate 14 reads `status.jsonl` from `origin/dev`. Add `bkit:merged` label, drop `bkit:failed`. `--summary=<ship-summary.md> --summary-missing=<line>` reads the summary before the close removes the worktree holding it (absent — PR merged on entry → the missing line) and copies it to `{OUTBOX}`; final return displays it verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, the star line, then how to silence both) as `## bkit Tips`, then offers a plain-English explanation on request. **HARD STOP**. |
|
|
998
1124
|
|
|
999
|
-
**Failure Path** books in `BOOK_ROOT` (not `--git-common-dir`), runs `bkit workflows fail` (aborts a rebase, appends `workflow-failed`, releases the lock, clears `.deferred-blocked`), and includes conditional handover via `@bkit-debug-abort-handover` writing `ship-handover.md` when max-retry exhausted.
|
|
1125
|
+
**Failure Path** books in `BOOK_ROOT` (not `--git-common-dir`), runs `bkit workflows fail` (aborts a rebase or merge, appends `workflow-failed`, releases the lock, clears `.deferred-blocked`), and includes conditional handover via `@bkit-debug-abort-handover` writing `ship-handover.md` when max-retry exhausted.
|
|
1000
1126
|
|
|
1001
1127
|
### Audits
|
|
1002
1128
|
|
|
1003
|
-
No command and no phase label. A template in `docs/templates/bkit-audit-*.md` is the procedure (sections, steps, gates). `@bkit-audit-generate` runs one template and writes `docs/audits/{YYYYMM}/{slug}.md`.
|
|
1129
|
+
No command and no phase label. A template in `docs/templates/bkit-audit-*.md` is the procedure (sections, steps, gates). `@bkit-audit-generate` runs one template and writes `docs/audits/{YYYYMM}/{slug}.md`.
|
|
1130
|
+
|
|
1131
|
+
- **If** that month already has this slug → `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`).
|
|
1132
|
+
|
|
1133
|
+
It writes only the report and the template's consumer-owned `Project Instructions` below `bkit:end`, refined each run.
|
|
1134
|
+
|
|
1135
|
+
- **If** an issue is named in the input and a tracker is wired → it posts the final summary there as one `--kind=audit` comment (`### Audit Summary: {slug}`), `STOPPED` runs included. This never gates.
|
|
1136
|
+
- **If** no issue is named and a tracker is wired → it runs a read-only search for the template's audit parent (`.bkit/trackers.md` § Issue shapes).
|
|
1137
|
+
- **If** found → the summary is posted there.
|
|
1138
|
+
- **If** none is open → `Recommended Next Step` suggests one, with the built comment saved to `{OUTBOX_ROOT}/audit-{slug}/parent-comment.md` to post as its first comment.
|
|
1139
|
+
|
|
1140
|
+
`Suggested Issues` rows are always filed as sub-issues of the parent, existing or new. Final return appends what `bkit tips --workflow=audit` prints (one tip, then how to silence it; no star line) as `## bkit Tips`, then offers a plain-English explanation on request. `/bkit-plan` reads a design doc, one or more of those reports, or both.
|
|
1004
1141
|
|
|
1005
1142
|
### `/bkit-auto` — phase-routed dispatch
|
|
1006
1143
|
|
|
1007
|
-
**Goal:** phase-routed cloud dispatcher. `{PHASE}` + `{ARG}` from args
|
|
1144
|
+
**Goal:** a phase-routed cloud dispatcher. It sends `{PHASE}` + `{ARG}` from its args to the matching phase skill. It has two top-level steps only, because the stale-run guard and the `bkit:auto` opt-in gate run cloud-side in `bkit-cloud.yml`'s ctx step, not in this file. **`MODE` = CI** (`ship`/`debug`, `{ARG}` = PR number): Step 1 resolves from the PR, Step 2 dispatches; **`MODE` = CI_DEV** (`debug`, `{ARG}` = FID slug — post-merge `dev` CI failure, no open PR): Step 1 sub-step 3 resolves `{FID}` / `{ISSUE_ID}` / `BRANCH` / `HEAD_SHA` from the slug and routes straight to the comment + dispatch; **`MODE` = BRIEF** (`design`/`plan`/`build`, `{ARG}` = issue): Step 1 → Step 2 — human `workflow_dispatch` = opt-in (`bkit-cloud.yml` offers `plan` / `build` only; `design` runs locally); the dispatched skill owns the brief and `status.jsonl` / worktree / FID. There is no worktree and no tracker state beyond a single comment line.
|
|
1008
1145
|
|
|
1009
1146
|
<!-- prettier-ignore -->
|
|
1010
1147
|
| Step | Notes |
|
|
1011
1148
|
| --- | --- |
|
|
1012
|
-
| 1 — Start Workflow | `bkit repo info --allow-detached` (holds `{BKIT}`, `{OUTBOX_ROOT}`), then one `bkit runs context --phase={PHASE} --arg={ARG}`: classifies `{PHASE}` → `MODE` (CI-status aliases `success`/`pass` → `ship`, `failure`/`fail` → `debug` let the Cursor dashboard paste `/bkit-auto $CI_STATUS $PR_NUMBER` literally; unknown → exit 3). `MODE` = CI: `gh pr view {ARG}` → branch / head / state (open required, exit 7) / URL; the CI run at that head (exit 8 when none); `{FID}` + `{ISSUE_ID}` from the PR-body marker, else the `feat/{FID}` branch (exit 9 when neither parses); `gh` missing → exit 80 → **Failure Path**. `MODE` = CI_DEV: `{ARG}` is the `{FID}` slug itself (allowlist first), `{ISSUE_ID}` = its leading issue segment, `BRANCH` = `dev`, `HEAD_SHA` = `origin/dev`; no PR, no run link. `MODE` =
|
|
1013
|
-
| 2 — Dispatch |
|
|
1149
|
+
| 1 — Start Workflow | `bkit repo info --allow-detached` (holds `{BKIT}`, `{OUTBOX_ROOT}`), then one `bkit runs context --phase={PHASE} --arg={ARG}`: classifies `{PHASE}` → `MODE` (CI-status aliases `success`/`pass` → `ship`, `failure`/`fail` → `debug` let the Cursor dashboard paste `/bkit-auto $CI_STATUS $PR_NUMBER` literally; unknown → exit 3). `MODE` = CI: `gh pr view {ARG}` → branch / head / state (open required, exit 7) / URL; the CI run at that head (exit 8 when none); `{FID}` + `{ISSUE_ID}` from the PR-body marker, else the `feat/{FID}` branch (exit 9 when neither parses); `gh` missing → exit 80 → **Failure Path**. `MODE` = CI_DEV: `{ARG}` is the `{FID}` slug itself (allowlist first), `{ISSUE_ID}` = its leading issue segment, `BRANCH` = `dev`, `HEAD_SHA` = `origin/dev`; no PR, no run link. `MODE` = BRIEF: `{ISSUE_ID}` = `{ARG}`. Gate 1 = `bkit steps gate --placeholder=` for the mode's values. The dispatched skill owns FID / `status.jsonl` / worktree. Create a fresh tracker comment header. Stateless: no `status.jsonl`, no `dev` commit. |
|
|
1150
|
+
| 2 — Dispatch | `{REF}` = `ref` from `bkit runs context` — the issue reference in a shape the dispatched workflow's own Step 1 parses (`#N` for GitHub, `ABC-123` for Linear / Jira). Route `{PHASE}` → `/bkit-ship {FID} {REF}` / `/bkit-debug {FID} {REF}` / `/bkit-design {REF}` / `/bkit-plan {REF}` / `/bkit-build {REF}`. Invoke via `Skill` (Claude) / `Task` (Cursor); dispatched skill owns its session from there. The regression-gate-verification gate that catches Vercel-ignore / partial-tier demotion lives in `/bkit-ship` Step 2 — Regression Guard (universal — also applies to manual `/bkit-ship` invocations that bypass the workflow). |
|
|
1014
1151
|
|
|
1015
|
-
**CI-class skip conditions:** one tracker no-op line, exit 0. Only real failures (missing args, tracker unreachable, malformed state) → Failure Path. Loop bound: `/bkit-debug` enforces `
|
|
1152
|
+
**CI-class skip conditions:** one tracker no-op line, then exit 0. Only real failures (missing args, tracker unreachable, malformed state) → Failure Path. Loop bound: `/bkit-debug` enforces `debug.fix` and `debug.soak` `maxAttempts` across every debug run of the feature; cloud counts only `dev` dispatches.
|
|
1016
1153
|
|
|
1017
1154
|
## Worktree Model
|
|
1018
1155
|
|
|
1019
|
-
All phase workflows run in `.worktrees/{FID}` (gitignored)
|
|
1156
|
+
All phase workflows run in `.worktrees/{FID}` (gitignored), with one worktree per FID. The IDE's main checkout is never touched.
|
|
1020
1157
|
|
|
1021
1158
|
**Step 2 — Worktree Setup** = `bkit worktrees setup --workflow= --fid= --month= --detect [--branch=]` (`--detect` reads `runtimeWorktrees` from `bkit runtime detect`; `--worktrees` forces mint mode), identical across 5 phases except branch choice. It cannot change the caller's directory, so it prints `worktreePath` and the workflow `cd`s into it.
|
|
1022
1159
|
|
|
@@ -1024,19 +1161,19 @@ All phase workflows run in `.worktrees/{FID}` (gitignored). One worktree per FID
|
|
|
1024
1161
|
| Mode | When | Does |
|
|
1025
1162
|
| --- | --- | --- |
|
|
1026
1163
|
| `created` | `--worktrees`, no `.worktrees/{FID}` | `git worktree prune`; adds the existing local `feat/{FID}`, else tracks `origin/feat/{FID}`, else cuts `feat/{FID}` off the base: a freshly fetched `origin/dev` (explicit refspec — a clone whose fetch refspec skips `dev` still gets a current base; origin unreachable → exit 4, nothing minted), or local `dev` when it is a fast-forward of `origin/dev` — dev pushes wait for a human, so local `dev` routinely holds commits `origin/dev` lacks; push `dev` before the feature PR. Local `dev` diverged from `origin/dev` → `origin/dev`, narrated. Writes the `.worktree-owned` marker in `{OUTBOX}` |
|
|
1027
|
-
| `resumed` | `--worktrees`, `.worktrees/{FID}` registered | `git fetch origin dev` + `git rebase` onto the same base (ship: no fetch, no rebase). Conflict → exit 3, rebase left in progress (§ Rebase Conflict Tiering); a rebase that cannot start → exit 9. A plain directory at the path → exit 10, never rebases the main checkout |
|
|
1164
|
+
| `resumed` | `--worktrees`, `.worktrees/{FID}` registered | `git fetch origin dev` + `git rebase` onto the same base (ship: no fetch, no rebase). An uncommitted tree (a failed ship's flush lands its record on dev and leaves the worktree as it was) is committed first as `chore({FID}): carry … bkit` (`carriedSha`), so any workflow can start after any failed one: an untracked log of the FID that the base already holds is dropped first (dev's copy wins, `carriedDropped`; one whose content differs is moved to the outbox's `{FID}/dropped-logs/` first), and the `bkit.workflows.worktree.copy` entries (the main checkout's and the worktree's lists) are never committed and alone do not count as uncommitted; a tracked one setup copied over is set aside for the rebase (`--autostash`) once nothing else is left. `engine-call` rows appended to the end of the tracked `status.jsonl` and `friction` rows appended to the end of the tracked `.bkit/friction.jsonl` after that commit are cut from those files before the rebase and appended again after it, not stashed, so a dev that appended to the same file cannot leave conflict markers or a stash entry behind; a rebase that stops part-way keeps them out of the tree and writes them to `rebase-resolve-log.md`. Conflict → exit 3, rebase left in progress (§ Rebase Conflict Tiering); a rebase that still cannot start (that commit refused) → exit 9. A plain directory at the path → exit 10, never rebases the main checkout |
|
|
1028
1165
|
| `adopted` | no `--worktrees` (cloud), or the session already sits on the branch | works in place on the current branch, `worktreePath` = repo root; no copy, no install |
|
|
1029
1166
|
|
|
1030
1167
|
Then, for `created` / `resumed` worktrees only:
|
|
1031
1168
|
|
|
1032
|
-
- **Copy:** each `package.json` `bkit.worktree.copy` entry (default `.env`, `.env.local`; files or folders) from the main checkout; `copied` / `copyMissing` list them and every missing entry is narrated
|
|
1033
|
-
- **Install:** every workflow (`bkit.worktree.install`, default true), frozen lockfile through the package manager
|
|
1169
|
+
- **Copy:** each `package.json` `bkit.workflows.worktree.copy` entry (default `.env`, `.env.local`; files or folders) from the main checkout; `copied` / `copyMissing` list them and every missing entry is narrated. No app path is hard-coded. An entry pointing outside the main checkout is skipped. Beside them, bkit links its own `.bkit/.env` (gitignored, so a fresh checkout has none) to the main checkout's copy — one source of truth across a token rotation — copying it where a symlink is refused (a copy bkit made is refreshed on the next setup); `bkitEnv` reports `linked` / `unchanged` / `copied` / `differs` (a differing file is left to read) / `none` (the main checkout holds none) / `failed` (neither link nor copy could be written, narrated). Never committed: `.bkit/.env` is excluded from every bkit `git add -A` beside the configured entries.
|
|
1170
|
+
- **Install:** every workflow (`bkit.workflows.worktree.install`, default true), frozen lockfile through the package manager. It is required because per-package `node_modules` symlinks are not inherited by worktrees, and without the install there is no `.husky/_`, so commits and pushes in the worktree skip the hooks. Install failure → exit 5; a package manager that could not run → exit 6; both → **Failure Path** in every workflow.
|
|
1034
1171
|
- **direnv:** a worktree `.envrc` byte-identical to the main checkout's gets `direnv allow` (`direnvAllowed`), so the worktree carries the trust given there and nothing more. A differing `.envrc`, direnv missing or failing → narrated, never fatal; a human reads it and runs `direnv allow`. No git hook can do it: `core.hooksPath` (`.husky/_`) exists only after the install.
|
|
1035
1172
|
- `logDir` created; `baseRef` = the base above; `baseSha` = `git merge-base {baseRef} HEAD` (design / plan anchor).
|
|
1036
1173
|
|
|
1037
1174
|
Refused (exit 7): `dev` / `main` as the working branch (debug: `main` only), a detached HEAD, or ship unable to switch to its branch.
|
|
1038
1175
|
|
|
1039
|
-
**`/bkit-debug` adopts, never mints.** Debug resumes an existing worktree, adds one for an existing `feat/{FID}`, or remediates on the session's branch in place
|
|
1176
|
+
**`/bkit-debug` adopts, never mints.** Debug resumes an existing worktree, adds one for an existing `feat/{FID}`, or remediates on the session's branch in place. It creates no new branch, because a fresh branch per debug run strands the fix off the surface whose CI actually failed. `main` is the one ineligible branch.
|
|
1040
1177
|
|
|
1041
1178
|
**Branch choice:**
|
|
1042
1179
|
|
|
@@ -1065,11 +1202,11 @@ Refused (exit 7): `dev` / `main` as the working branch (debug: `main` only), a d
|
|
|
1065
1202
|
|
|
1066
1203
|
## Tracker Integration
|
|
1067
1204
|
|
|
1068
|
-
Pluggable via `bkit install --tracker=<github|linear|jira|none>`. Per-tracker MCP
|
|
1205
|
+
Pluggable via `bkit install --tracker=<github|linear|jira|none>`. `bkit` verbs read and write the tracker (GitHub through `gh` with `BKIT_GH_TOKEN`, Linear through its GraphQL API, Jira through the Rovo MCP endpoint over HTTP) and print `tracker`; the tracker MCP runs only when a verb exits 80 or prints `done` = false. Per-tracker MCP fallback tool names and call shapes sit in each workflow's header tracker block as `github` / `linear` / `jira` / `none` blocks; installer keeps chosen, drops others when mirroring `.claude/commands/` + `.cursor/commands/` (§ Tracker Blocks). `.bkit/trackers.md` = marker contract + cross-cutting conventions only.
|
|
1069
1206
|
|
|
1070
1207
|
### Phase labels (mutually exclusive)
|
|
1071
1208
|
|
|
1072
|
-
Phase labels carry `bkit:` namespace
|
|
1209
|
+
Phase labels carry the `bkit:` namespace, so they cannot clash with consumer labels. Workflow code keeps them mutually exclusive: drop the prior phase label from `{LABELS}` before adding the new one. A phase start also drops every `next:*` label (next best workflow for an issue no workflow has started) and `bkit:failed` (a new run supersedes the failed one).
|
|
1073
1210
|
|
|
1074
1211
|
<!-- prettier-ignore -->
|
|
1075
1212
|
| Label | Meaning |
|
|
@@ -1081,19 +1218,19 @@ Phase labels carry `bkit:` namespace — no consumer clash. Mutual exclusion in
|
|
|
1081
1218
|
| `bkit:ship` | `/bkit-ship` running |
|
|
1082
1219
|
| `bkit:merged` | `/bkit-ship` completed; PR merged to `dev`; issue left **In Review** (open) — a human reviews post-merge and closes manually (bkit never auto-closes) |
|
|
1083
1220
|
|
|
1084
|
-
|
|
1221
|
+
The phase label is kept through Close. The tracker state (GitHub `open`, Linear / Jira review state) carries the completion signal, and the label tells reviewers which workflow finished and names the next best one (`bkit:design` → plan, `bkit:plan` → build, `bkit:build` / `bkit:debug` → ship; with `bkit:failed` → debug). Ship exception: Close swaps `bkit:ship` → `bkit:merged`.
|
|
1085
1222
|
|
|
1086
1223
|
### Additive labels (do not drop phase)
|
|
1087
1224
|
|
|
1088
1225
|
<!-- prettier-ignore -->
|
|
1089
1226
|
| Label | Added by | When |
|
|
1090
1227
|
| --- | --- | --- |
|
|
1091
|
-
| `bkit:auto` | Human (via tracker UI) at issue creation | Opt-in gate for `/bkit-auto` CI-mode (ship/debug) dispatch. Removed by any workflow that finds `bkit:auto` absent on the linked issue (kill-switch propagation). |
|
|
1228
|
+
| `bkit:auto` | Human (via tracker UI) at issue creation | Opt-in gate for `/bkit-auto` CI-mode (ship / debug) dispatch. Removed by any workflow that finds `bkit:auto` absent on the linked issue (kill-switch propagation). |
|
|
1092
1229
|
| `bkit:failed` | Failure Path of any workflow | Workflow hit its Failure Path; human triage required. Phase label persists alongside, so reviewers see which workflow failed. Cleared by every phase start (`--phase=*` implies `--failed=off`), including `/bkit-debug` Step 1 and `/bkit-ship` Step 14 `bkit:merged`. |
|
|
1093
1230
|
|
|
1094
1231
|
### Tracker-specific state
|
|
1095
1232
|
|
|
1096
|
-
Issue state semantics (GitHub `open`/`closed` + Projects v2; Linear / Jira `progress` / `review` from `bkit.linear` / `bkit.jira`, never done) inline as per-tracker blocks:
|
|
1233
|
+
Issue state semantics (GitHub `open`/`closed` + Projects v2; Linear / Jira `progress` / `review` from `bkit.tracker.linear` / `bkit.tracker.jira`, never done) inline as per-tracker blocks:
|
|
1097
1234
|
|
|
1098
1235
|
<!-- prettier-ignore -->
|
|
1099
1236
|
| Snippet | When |
|
|
@@ -1102,15 +1239,15 @@ Issue state semantics (GitHub `open`/`closed` + Projects v2; Linear / Jira `prog
|
|
|
1102
1239
|
| `issue-update-review` | Close Workflow of `/bkit-design`, `/bkit-plan`, `/bkit-build`, `/bkit-debug`. Hand-off state (GitHub no-op — phase label carries signal; Linear / Jira `review`). |
|
|
1103
1240
|
| `issue-update-merged` | `/bkit-ship` Step 14. Ship terminal — drop phase labels, add `bkit:merged`; GitHub left **open**, Linear / Jira `review`. bkit never closes / never sets Done — a human closes on acceptance (merge != acceptance). |
|
|
1104
1241
|
| `issue-update-failed` | Failure Path. Adds `bkit:failed` additive label. |
|
|
1105
|
-
| `issue-update-status` | Step 1 (design/plan/build/debug/ship) → "In progress"; phase Close (design/plan/build/debug) → "In review"; `/bkit-ship` Step 14 → "In review" (never "Done" — the board mirrors the issue, which stays open for human close). GitHub Projects v2 board (`bkit.github.project`; skipped if unset/absent). Linear / Jira no-op (issue state already carries it). |
|
|
1242
|
+
| `issue-update-status` | Step 1 (design/plan/build/debug/ship) → "In progress"; phase Close (design/plan/build/debug) → "In review"; `/bkit-ship` Step 14 → "In review" (never "Done" — the board mirrors the issue, which stays open for human close). GitHub Projects v2 board (`bkit.tracker.github.project`; skipped if unset / absent). Linear / Jira no-op (issue state already carries it). |
|
|
1106
1243
|
|
|
1107
1244
|
### Comment lifecycle
|
|
1108
1245
|
|
|
1109
|
-
new comment
|
|
1246
|
+
Each workflow step posts a new comment through the step's `bkit` verb (`--post`; the tracker MCP when `tracker.done` = false). Step 1 posts the first comment, and each later step posts its own. NEVER edit or paraphrase a comment, and never carry comment IDs forward. The templates are in § Comment Lifecycle.
|
|
1110
1247
|
|
|
1111
1248
|
### Issue blockers (`/bkit-build` Step 1)
|
|
1112
1249
|
|
|
1113
|
-
`/bkit-build` Step 1:
|
|
1250
|
+
`/bkit-build` Step 1: `bkit issues blocked-by --issue` reads the blocker relations (GitHub: the `###### bkit:blocked-by start` … `end` block in the body, then each blocker's state; Linear: the issue's inverse `blocks` relations; Jira: JQL `issue in linkedIssues('{ISSUE_ID}', 'is blocked by')`) and prints `{blockers: [{id, state}], open}`; exit 80 → the tracker MCP reads them. `open` > 0 → Failure Path `Blocked by {BLOCKER_ID} (state: {BLOCKER_STATE})`. Workflows never write those edges. A human sets them, directly or by running `@bkit-utility-update-tracker`.
|
|
1114
1251
|
|
|
1115
1252
|
## GitHub Integration
|
|
1116
1253
|
|
|
@@ -1119,12 +1256,12 @@ new comment per workflow step via tracker MCP. Step 1 = first comment; later ste
|
|
|
1119
1256
|
- **Base branch:** `dev`. PRs always target `dev`, never `main`.
|
|
1120
1257
|
- **Feature branch:** `feat/{FID}` for design / plan / build / ship.
|
|
1121
1258
|
- **Debug creates no branch:** it adopts `feat/{FID}` when that branch still exists, else the session's current branch in place. A per-run remediation branch strands the fix off the surface whose CI failed and multiplies branches across debug attempts.
|
|
1122
|
-
- **Branch eligibility** (`/bkit-ship` Step
|
|
1123
|
-
-
|
|
1259
|
+
- **Branch eligibility** (`/bkit-ship` Step 1): ships `SHIP_BRANCH` (see Workflow Primitives § Branch eligibility); `dev` / `main` refused (the engine's exit 7 prints "refusing to ship ... releases stay manual"; Step 1 releases the lock and STOPs); a branch not named for `{FID}` — or for `{ISSUE_ID}` when one exists — gets a warning, not a stop (`worktrees setup --issue=` prints it as `branchWarning` and on stderr). `/bkit-debug` deliberately does not gate this way. It accepts any branch but `main`, because the branch carrying the failure is the branch the fix belongs on.
|
|
1260
|
+
- NEVER push to `main` (the release branch).
|
|
1124
1261
|
|
|
1125
1262
|
### GitHub calls used by the pipeline
|
|
1126
1263
|
|
|
1127
|
-
PR / CI reads and writes go through `bkit` commands (exit 80 → the mapped MCP tool,
|
|
1264
|
+
PR / CI reads and writes go through `bkit` commands (exit 80 → the mapped MCP tool, `.bkit/cli.md`); only the calls no command wraps stay as raw `gh`.
|
|
1128
1265
|
|
|
1129
1266
|
<!-- prettier-ignore -->
|
|
1130
1267
|
| Purpose | Call |
|
|
@@ -1132,12 +1269,14 @@ PR / CI reads and writes go through `bkit` commands (exit 80 → the mapped MCP
|
|
|
1132
1269
|
| `OWNER_REPO` (Step 1 of every phase) | `bkit repo info` (`gh`, else the origin remote) |
|
|
1133
1270
|
| Dispatch-permission preflight (ship Step 1) | `bkit repo preflight --owner-repo` (advisory: warns and continues, exit 0) |
|
|
1134
1271
|
| PR lookup, PR-mode detection | `bkit prs probe [--head= --base= --state= --number=]` |
|
|
1135
|
-
| PR creation (build Step
|
|
1272
|
+
| PR creation (build Step 16, debug Step 11 LOCAL, design / plan PR close, ship Step 2 when no PR exists) | `bkit prs open` (base pinned `dev`, marker in body) |
|
|
1136
1273
|
| CI presence / completion, CI-Dispatch Gate | `bkit runs wait`, `bkit runs dispatch` |
|
|
1137
1274
|
| Ship merge gate, squash-commit CI | `bkit runs gate` |
|
|
1138
1275
|
| Squash merge (ship Step 10; design / plan PR close) | `bkit prs merge` / `bkit branches land` → `gh pr merge {PR} --squash [--match-head-commit <head>] --subject "…" --body ""` — empty body strips feature `bkit [skip ci]` |
|
|
1139
|
-
| Path B
|
|
1276
|
+
| Path B integration (ship Step 4) | `bkit branches sync --merge`, then `bkit branches push --mode=plain` (never forced) |
|
|
1140
1277
|
| PR check-rollup assert (ship Step 2) | `bkit prs checks --number` |
|
|
1278
|
+
| Feature-branch push to open a missing PR, regenerate push, merge push, bookkeeping push (ship Steps 2 / 4 / 8 / 10) | `bkit branches push --mode=plain` (never forced) |
|
|
1279
|
+
| `bkit [force build]` PR-title marker (build Step 16) | `bkit branches force-build` → `gh pr edit --title` |
|
|
1141
1280
|
| `bkit [verbose ci]` PR-title marker (debug Steps 9 / 11) | `gh pr edit --title` |
|
|
1142
1281
|
|
|
1143
1282
|
Code PRs never merge locally; `/bkit-ship` merges with `bkit prs merge` (`gh pr merge` underneath).
|
|
@@ -1150,58 +1289,63 @@ Conventional Commits — `{type}({FID}): {summary}`.
|
|
|
1150
1289
|
| Type | When |
|
|
1151
1290
|
| --- | --- |
|
|
1152
1291
|
| `docs` | Doc-only changes (handover, ship close-workflow on `dev`); abort summary commits |
|
|
1153
|
-
| `chore` | All per-step workflow commits (worktree-setup, summary, close-workflow, push-remediation attempt N/max, etc.) + pre-worktree carry-over |
|
|
1292
|
+
| `chore` | All per-step workflow commits (worktree-setup, summary, close-workflow, push-remediation attempt N / max, etc.) + pre-worktree carry-over |
|
|
1154
1293
|
| `feat` | Build implementation (PR title only) |
|
|
1155
1294
|
|
|
1156
1295
|
### CI / Vercel commit tags
|
|
1157
1296
|
|
|
1158
|
-
Precedence: `bkit [force build]` on head commit
|
|
1297
|
+
Precedence: `bkit [force build]` wins. bkit's own `bkit-ci.yml` reads markers from the PR title on `pull_request` events and from the head commit on pushes; the consumer template reads the PR title on `pull_request`, else the head commit (`workflow_dispatch` included).
|
|
1159
1298
|
|
|
1160
1299
|
<!-- prettier-ignore -->
|
|
1161
1300
|
| Tag | Effect |
|
|
1162
1301
|
| --- | --- |
|
|
1163
1302
|
| `bkit [skip ci]` | GitHub Actions skip the workflow / `vercel-build` sets `run_level=none`. |
|
|
1164
|
-
| `bkit [force build]` | Forces full CI + Vercel build even on docs-only paths. Used by `/bkit-build` Step
|
|
1303
|
+
| `bkit [force build]` | Forces full CI + Vercel build even on docs-only paths. Used by `/bkit-build` Step 16 when the branch changes migration sources: `bkit branches force-build` sets it in the PR title and on an empty marker commit; `bkit prs merge` drops it from the squash subject it builds from the title. |
|
|
1165
1304
|
|
|
1166
|
-
**Docs-only commits:** workflows append `bkit [skip ci]` (CI suppression).
|
|
1305
|
+
**Docs-only commits:** workflows append `bkit [skip ci]` (CI suppression). There is no `bkit [skip build]` marker, because docs-only is not app-affected and host affected-detection cancels the build without it. Hosts that cancel only on `[skip build]` will build docs-only workflow commits, so switch them to affected-detection.
|
|
1167
1306
|
|
|
1168
1307
|
<!-- prettier-ignore -->
|
|
1169
1308
|
| Workflow commit | Tags |
|
|
1170
1309
|
| --- | --- |
|
|
1171
1310
|
| `chore({FID}): pre-worktree uncommitted changes` (design / plan / build Step 2, `bkit ledgers commit --only-if-dirty-tracked`) | `bkit [skip ci]` |
|
|
1172
|
-
| `chore({FID}): {step-slug}` for per-step in-worktree commits (e.g. `worktree-setup`, `branch-sync`, `install-skills`, `plan-
|
|
1173
|
-
| `chore({FID}): summary bkit [skip ci]` (design Step 10 summary, plan Step
|
|
1311
|
+
| `chore({FID}): {step-slug}` for per-step in-worktree commits (e.g. `worktree-setup`, `branch-sync`, `install-skills`, `plan-tests group N attempt M`, `plan-execute group N attempt M`, `plan-verify group N attempt M`, `failure-diagnose attempt N`, `build-challenge attempt N`, `summary`, `create-pr`, ship `merge-pr attempt N`, ship `prune-skills`, ship `update-docs-summary`) | none — in-worktree, never visible to CI on `dev` |
|
|
1312
|
+
| `chore({FID}): summary bkit [skip ci]` (design Step 10 summary, plan Step 7 summary) | `bkit [skip ci]` |
|
|
1174
1313
|
| `fix({FID}): {description}` (debug Step 7 failure-remediate) | none — Step 9 pushes this commit directly so `fix(...)` becomes the CI-triggering HEAD (dodges `^chore:`-prefix Vercel-ignore rules and partial-tier demotion). `{description}` derived from first `DONE — Step` line in `debug-failure-remediate-{NORMAL_ATTEMPT}-log.md`. Debug Step 8 adds no intermediate `chore(...)` commit before push. |
|
|
1175
1314
|
| `docs({FID}): ship bookkeeping` (ship Step 8, on `{SHIP_BRANCH}` before the merge) | `bkit [skip ci]` — CI is carried forward from `CODE_HEAD` (§ `/bkit-ship` — Validated-head carry-forward), so the push must not fire a run. |
|
|
1176
1315
|
| `docs({FID}): ship DONE` (ship Step 14 close-workflow on `dev`, or its `ship-close/{FID}` PR squash subject) | `bkit [skip ci]` |
|
|
1177
1316
|
| `docs({FID}): {phase} aborted` (design / plan / build / debug Failure Path record on the feature branch) | `bkit [skip ci]` |
|
|
1178
1317
|
| `chore({FID}): {phase} FAILED` (ship Failure Path — the single flush, carrying the handover and the reconciled branch-side artifacts, so ship emits no `aborted` commit; design / plan / build / debug Failure Path from a `dev` / `main` checkout, logs and ledgers only) | `bkit [skip ci]` |
|
|
1179
|
-
| `chore({FID}): close-workflow` (build Step
|
|
1318
|
+
| `chore({FID}): close-workflow` (build Step 16 — opted-in: `bkit [auto route]` suffix when issue carried `bkit:auto` at close time) | none on base commit; opted-in adds `bkit [auto route]` (loud, not a suppressor) — final HEAD on push, fires `pull_request` synchronize + CI auto-route gate |
|
|
1180
1319
|
| `chore({FID}): close-workflow` (debug Step 11 PR-mode — opted-in) | none / `bkit [auto route]` (PR-mode, conditional) — same as build |
|
|
1181
|
-
| `chore({FID}): create-pr` (debug Step 11 local-mode — opted-in) |
|
|
1182
|
-
| `chore({FID}):
|
|
1183
|
-
| `
|
|
1320
|
+
| `chore({FID}): create-pr` (debug Step 11 local-mode — opted-in; `bkit branches push --commit`, one per run via an `engine-action` row) | `bkit [verbose ci]`; opted-in adds `bkit [auto route]` (local-mode, conditional) — CI-triggering HEAD in local-mode |
|
|
1321
|
+
| `chore({FID}): force build` (build Step 16, `bkit branches force-build`, migrations changed) | `bkit [force build]`; opted-in adds `bkit [auto route]` — the CI-triggering HEAD |
|
|
1322
|
+
| `chore({FID}): carry uncommitted work before merging dev` / `merge dev` / `regenerate after merging dev` (ship Step 4, `bkit branches sync --merge`, pushed plain) | none — never `bkit [skip ci]`, never `bkit [auto route]`. The merge carries `dev`'s code, so a skip token on its HEAD would leave the open PR's checks vacuously green, and the pre-push hook refuses that push. The push starts CI at the merged head, and Step 9 waits on that run. A server-side update-branch is never used — GitHub ignores `merge=union`, so a PR whose ledgers both sides appended stays CONFLICTING there while the local merge is clean. |
|
|
1323
|
+
| `{title} (#{PR_NUMBER})` squash-merge commit (ship Step 10 `bkit prs merge`, GitHub-authored, lands on `dev`) | none / `bkit [auto route]` (opted-in: `bkit:auto` re-read from the tracker immediately before merge, passed as `--label=`) — the CI-triggering HEAD that admits `bkit-cloud.yml`'s post-merge `dev` free-tier gate. Distinct from the Step 4 row above: GitHub authors this commit at merge time. |
|
|
1324
|
+
|
|
1325
|
+
**CI trigger mechanic (build / debug / ship aligned):** the last push to the CI-validated ref must leave HEAD without `bkit [skip ci]`.
|
|
1326
|
+
|
|
1327
|
+
- **If** it does not → `pull_request` (build / debug) or `push` (ship) is suppressed, `statusCheckRollup` stays empty, and Ship Step 2's fail-fast admits a vacuously green PR.
|
|
1184
1328
|
|
|
1185
|
-
|
|
1329
|
+
Build / debug trigger CI in close-workflow; ship triggers it through the squash merge subject. The CI-Dispatch Gate below enforces this (§ CI-Dispatch Gate).
|
|
1186
1330
|
|
|
1187
1331
|
### CI-Dispatch Gate (shared, single source)
|
|
1188
1332
|
|
|
1189
|
-
|
|
1333
|
+
An outcome-verification gate. After the final loud push, it confirms that the bkit CI check dispatched for the exact pushed HEAD: a bounded poll, then one self-heal with a clean `re-trigger` commit, then a named verdict. The pre-push HEAD-subject check is the fast-fail; the post-push poll is the outcome verification. It fires post-final-push only, so there are zero mid-build CI triggers.
|
|
1190
1334
|
|
|
1191
|
-
**Invoked by orchestrators
|
|
1335
|
+
**Invoked by orchestrators**, not by a git hook, because the invariant depends on context: bkit intentionally pushes `[skip ci]` HEADs along the way. The HEAD-message clause is `bkit branches push --require-ci` (exit 6 on a CI-suppressing token in the HEAD message, body included); the PR-title clause is `bkit prs open` (exit 4 on a token in `--title`); the poll is `bkit runs dispatch`:
|
|
1192
1336
|
|
|
1193
|
-
- **Build Step
|
|
1194
|
-
- **Debug Step 11 PR-mode:** close-workflow push (sub-step 2, `--require-ci`) = CI trigger; gate in sub-step
|
|
1337
|
+
- **Build Step 16:** close-workflow commit → `bkit branches push --mode=feature --require-ci` (no PR yet, no CI; on an unshared branch the push first merges `origin/dev`'s `docs/` and ledger commits, as `branches sync --merge-docs` does, so the PR it opens never conflicts on a union-merged ledger) → `bkit prs open` (the PR creation fires CI) → `bkit runs dispatch --pr=`.
|
|
1338
|
+
- **Debug Step 11 PR-mode:** close-workflow push (sub-step 2, `--require-ci`) = CI trigger; gate in sub-step 7.
|
|
1195
1339
|
- **Debug Step 11 LOCAL-mode:** create-pr push (sub-step 6, `--require-ci`) = CI trigger, its block re-deriving `AUTO_ROUTE_SUFFIX`; gate in sub-step 7.
|
|
1196
|
-
- **Ship:**
|
|
1197
|
-
- **Ship Step 9 duplicate-dispatch probe (not the gate):** `bkit runs wait --head=<VALIDATED_HEAD> --branch= --until=present --dispatch-if-absent` probes for a CI-workflow run at that head, presence only (`SHIP_PROBE_ATTEMPTS` x `SHIP_PROBE_INTERVAL_S`), and runs `gh workflow run {bkit.ciWorkflow}` only on no-run. The head move it follows (Path B
|
|
1340
|
+
- **Ship:** out of scope. Step 14 reads the squash commit's CI with `bkit runs gate --head=<SQUASH_SHA>` and records `ship-merge-ci`. CI-Dispatch at ship would mask the "essential tests skipped" signal that ship backstops.
|
|
1341
|
+
- **Ship Step 9 duplicate-dispatch probe (not the gate):** `bkit runs wait --head=<VALIDATED_HEAD> --branch= --until=present --dispatch-if-absent` probes for a CI-workflow run at that head, presence only (`SHIP_PROBE_ATTEMPTS` x `SHIP_PROBE_INTERVAL_S`), and runs `gh workflow run {bkit.testing.ciWorkflow}` only on no-run. The head move it follows (Path B's Step 4 push of the local `origin/dev` merge) carries `[skip ci]`, so no `pull_request` run fires and the probe dispatches one; a run that did fire at the same SHA is found and reused instead, and the template `bkit-ci.yml` groups `pull_request` by PR number but `workflow_dispatch` by ref — different groups, so neither cancels the other and both runs complete. The probe carries no outcome vocabulary and is never a pass condition (no `self-healed`/`no-ci` path exists at ship): the head-anchored completion poll (`--until=completed`) and `bkit runs gate` at Gate 10 still own the verdict, so the "masks essential tests skipped" objection does not apply. Probe `err` → dispatch. Row `ship-revalidate-dispatch` records `probe` / `dispatched` / `attempts`. The 60s budget is load-bearing: a `pull_request` run surfacing after it reproduces the duplicate this probe removes. Auto-fired runs typically appear ~10-20s after the push, but auto-fire is intermittent, so the probe must keep failing safe to dispatch rather than reading a slow or absent run as "no CI".
|
|
1198
1342
|
- **Ship Gate 10 + squash `--body ""`:** merge — squash subject = dev HEAD.
|
|
1199
1343
|
|
|
1200
1344
|
**Gate outcomes (4-state terminal verdict):**
|
|
1201
1345
|
|
|
1202
1346
|
- `dispatched` — bkit CI check on pushed HEAD within poll budget. Proceed.
|
|
1203
1347
|
- `self-healed` — poll exhausted, HEAD clean; one empty `re-trigger` commit (`AUTO_ROUTE_SUFFIX`) + re-poll; run appeared. Proceed.
|
|
1204
|
-
- `no-ci` — poll exhausted, HEAD clean, re-trigger also dispatched nothing, and `.github/workflows/{bkit.ciWorkflow}` (default `bkit-ci.yml`) absent — no consumer CI workflow. Logged pass; not Failure Path.
|
|
1348
|
+
- `no-ci` — poll exhausted, HEAD clean, re-trigger also dispatched nothing, and `.github/workflows/{bkit.testing.ciWorkflow}` (default `bkit-ci.yml`) absent — no consumer CI workflow. Logged pass; not Failure Path.
|
|
1205
1349
|
- `unresolved` — sub-reason below → **Failure Path** after verdict recorded.
|
|
1206
1350
|
|
|
1207
1351
|
**Sub-reason codes (→ `unresolved`):**
|
|
@@ -1209,14 +1353,14 @@ Outcome-verification gate: after final loud push, confirms bkit CI check dispatc
|
|
|
1209
1353
|
- `timeout-dirty` — poll exhausted and HEAD carries CI suppressor; refuse re-trigger dirty HEAD.
|
|
1210
1354
|
- `retrigger-suppressed` — re-trigger HEAD carries suppressor; cannot discriminate `no-ci` vs suppression → `unresolved`, not `no-ci`.
|
|
1211
1355
|
- `gh-error` — every poll iteration errored.
|
|
1212
|
-
- `ci-declared-no-run` — clean re-trigger dispatched nothing, yet `bkit runs declared` finds the workflow file (`.github/workflows/{bkit.ciWorkflow}`).
|
|
1356
|
+
- `ci-declared-no-run` — clean re-trigger dispatched nothing, yet `bkit runs declared` finds the workflow file (`.github/workflows/{bkit.testing.ciWorkflow}`). A broken workflow (invalid YAML → startup failure, zero check runs; renamed trigger / jobs) looks identical to no CI from the PR side, so a declared workflow's silence counts as a failure, never `no-ci`.
|
|
1213
1357
|
|
|
1214
1358
|
**Named symbols (every gate site — identical, owned by `bkit runs dispatch`):**
|
|
1215
1359
|
|
|
1216
1360
|
- `--budget-s` 60, `--interval-s` 10 (6 attempts).
|
|
1217
1361
|
- Log prefix `[bkit-runs]`.
|
|
1218
1362
|
- Self-heal cap = 1.
|
|
1219
|
-
- Dispatch probe: the capstone's lane namespace — `bkit.
|
|
1363
|
+
- Dispatch probe: the capstone's lane namespace — `bkit.testing.ciCapstone` minus its last `-segment` (`bkit-tests-check` → `bkit-tests`), case-insensitive, matched on check name or context. Any `bkit-tests-*` answers "did CI dispatch". There is no alias for other check names. Do not narrow it to one lane, because a lane rename would read as "no CI". Do not widen it to "any check", because Vercel/Renovate/cloud would false `dispatched`. Build / debug: PR rollup (`runs wait --pr`); ship: workflow-run shape (`runs wait --head --branch`).
|
|
1220
1364
|
|
|
1221
1365
|
**`ciDispatch` NDJSON field (additive on `step-done` records — backward-compatible with the fold):**
|
|
1222
1366
|
|
|
@@ -1232,60 +1376,64 @@ Outcome-verification gate: after final loud push, confirms bkit CI check dispatc
|
|
|
1232
1376
|
|
|
1233
1377
|
`reason` omitted when `dispatched`/`self-healed`/`no-ci`. The fold merges a step row's fields as-is — extra keys pass through (additive, backward-compatible).
|
|
1234
1378
|
|
|
1235
|
-
**`ciDispatch` step-done LOCAL-only (intentional non-push):** `bkit steps done --field=ciDispatch=… --commit=none` appends locally only
|
|
1379
|
+
**`ciDispatch` step-done LOCAL-only (intentional non-push):** `bkit steps done --field=ciDispatch=… --commit=none` appends locally only, and nothing commits or pushes it afterward. A post-gate commit changes the PR HEAD: a `[skip ci]` verdict commit empties the rollup (buried marker), and a clean commit fires a second CI run. Do not "fix" this with a post-gate commit+push.
|
|
1236
1380
|
|
|
1237
1381
|
**Per-site AUTO_ROUTE sourcing:**
|
|
1238
1382
|
|
|
1239
|
-
Every site derives `AUTO_ROUTE_SUFFIX`
|
|
1383
|
+
Every site derives `AUTO_ROUTE_SUFFIX` in the same bash fence that consumes it, from the labels the workflow re-read (`bkit issues fetch --outbox`, the tracker MCP on exit 80): `bkit issues labels {LABEL_FLAGS}` prints `autoRouteSuffix` (`" bkit [auto route]"` on an exact `bkit:auto`, else empty), and the fence passes it as `bkit runs dispatch --auto-route-suffix=`. Never carry the suffix itself across a fence or step: no shell state (nor a `mktemp` path published via `$GITHUB_ENV`) survives a Bash-tool-call boundary.
|
|
1240
1384
|
|
|
1241
|
-
- **Build Step
|
|
1242
|
-
- **Debug Step 11:** derived in the close / create-pr commit block (sub-steps 2 /
|
|
1385
|
+
- **Build Step 16:** derived in the dispatch block itself.
|
|
1386
|
+
- **Debug Step 11:** derived in the close / create-pr commit block (sub-steps 2 / 6) for the commit subject, and again in the gate block (sub-step 7) for the dispatch.
|
|
1243
1387
|
|
|
1244
1388
|
**Re-trigger commit:** `chore({FID}): re-trigger{AUTO_ROUTE_SUFFIX}`, created and pushed by `bkit runs dispatch` — opted-in issues carry `bkit [auto route]`. § `bkit [auto route]` Marker Propagation applies.
|
|
1245
1389
|
|
|
1246
|
-
**Contract (
|
|
1390
|
+
**Contract (deny-list — never an allow-list):**
|
|
1247
1391
|
|
|
1248
|
-
- **HEAD-message clause** (`bkit branches push --require-ci`, at the final CI-triggering push): scans the full message, body included
|
|
1392
|
+
- **HEAD-message clause** (`bkit branches push --require-ci`, at the final CI-triggering push): scans the full message, body included, because GitHub reads the whole commit message for skip tokens, so a suppressor in the body kills CI even with a clean subject line. `bkit runs dispatch` scans the pushed head's body again after the push (`scanResult`, exit 4).
|
|
1249
1393
|
- **PR-title clause** (`bkit prs open` at create-pr; ship Step 10's inline title check before the squash).
|
|
1250
|
-
- **Deny-list tokens (HEAD message + PR title):** `[skip ci]`, `[ci skip]`, `[no ci]`, `[skip actions]`, `[actions skip]` — GitHub-native CI suppressors. `[skip build]`
|
|
1394
|
+
- **Deny-list tokens (HEAD message + PR title):** `[skip ci]`, `[ci skip]`, `[no ci]`, `[skip actions]`, `[actions skip]` — GitHub-native CI suppressors. `[skip build]` is not checked: it is a host build-cancel convention, not platform-native, so it has no place in a stack-agnostic gate.
|
|
1251
1395
|
- **Legitimate loud tokens (deny-list, auto-pass):** `bkit [auto route]`, `bkit [verbose ci]`, `bkit [force build]`.
|
|
1252
|
-
- **Hard-fail loud:** name offending subject/title + fix → Failure Path. No silent auto-fix.
|
|
1396
|
+
- **Hard-fail loud:** name offending subject / title + fix → Failure Path. No silent auto-fix.
|
|
1253
1397
|
- **Escape hatch:** `bkit [force build]` on HEAD forces full CI + host build; not a suppressor.
|
|
1254
1398
|
|
|
1255
|
-
Rationale: invariant
|
|
1399
|
+
Rationale: the invariant depends on context, because bkit pushes `[skip ci]` along the way (build `worktree-setup`) and to `dev` (status bookkeeping). A blanket pre-push hook would block legitimate pushes. Only the orchestrator knows which push is the final loud one.
|
|
1256
1400
|
|
|
1257
1401
|
<!-- prettier-ignore -->
|
|
1258
1402
|
| Workflow | Step | Mechanic | Why this form |
|
|
1259
1403
|
| --- | --- | --- | --- |
|
|
1260
|
-
| `/bkit-build` |
|
|
1261
|
-
| `/bkit-debug` |
|
|
1262
|
-
| `/bkit-debug` |
|
|
1404
|
+
| `/bkit-build` | 16 (close-workflow) | Final commit `chore({FID}): close-workflow`, no skip tags + `bkit branches push --require-ci` + `bkit prs open` + CI-Dispatch poll | Drops `bkit [skip ci]` from the existing status commit; the PR creation on that head fires `pull_request`; gate confirms dispatch |
|
|
1405
|
+
| `/bkit-debug` | 11 (close-workflow) PR-mode | Final commit `chore({FID}): close-workflow`, no skip tags + `git push` + CI-Dispatch poll | PR-mode: close-workflow push is the CI-triggering push; gate in sub-step 7 |
|
|
1406
|
+
| `/bkit-debug` | 11 (close-workflow) LOCAL-mode | Separate create-pr push in sub-step 6 + CI-Dispatch poll | LOCAL-mode: create-pr push is the CI-triggering push; gate in sub-step 7 |
|
|
1263
1407
|
| `/bkit-ship` | 10 (merge-pr) | `bkit prs merge` (`gh pr merge --squash --body ""`) — squash subject becomes dev HEAD, body empty | `gh pr merge` is the only API; empty body strips PR-body `bkit [skip ci]` from the squash subject. Step 14 then gates the squash commit with `bkit runs gate --squash-of=<PR>` (not a CI-Dispatch Gate) |
|
|
1264
1408
|
| `/bkit-ship` | 8 (pre-merge bookkeeping) | `docs({FID}): ship bookkeeping bkit [skip ci]` pushed to `{SHIP_BRANCH}` | Docs, logs, ledgers, skill removals ride the PR; CI carried forward from `CODE_HEAD` by the gate's `--validated`, so no run is spent on them. |
|
|
1265
|
-
| `/bkit-ship` |
|
|
1409
|
+
| `/bkit-ship` | 14 (post-merge close) | `docs({FID}): ship DONE bkit [skip ci]` → `dev`, or a `ship-close/{FID}` PR when `dev` refuses the push | Post-merge status / telemetry only; PR already merged, dev's CI fired by Step 10, no re-trigger needed. |
|
|
1266
1410
|
|
|
1267
|
-
All intermediate workflow commits
|
|
1411
|
+
All intermediate workflow commits keep `bkit [skip ci]`. Only the trailing `close-workflow` (debug LOCAL: `create-pr`) is unmarked. It is the last commit before the final push, and every close pushes it explicitly.
|
|
1268
1412
|
|
|
1269
1413
|
## Permissions (`.claude/settings.json`)
|
|
1270
1414
|
|
|
1271
|
-
Without `acceptEdits` / wildcard allow surface, every `Bash`, `Edit`, `Write`, MCP, or skill call prompts mid-workflow
|
|
1415
|
+
Without `acceptEdits` / a wildcard allow surface, every `Bash`, `Edit`, `Write`, MCP, or skill call prompts mid-workflow, which breaks end-to-end runs.
|
|
1272
1416
|
|
|
1273
1417
|
<!-- prettier-ignore -->
|
|
1274
1418
|
| Bucket | Patterns | Purpose |
|
|
1275
1419
|
| --- | --- | --- |
|
|
1276
1420
|
| `allow` | `Bash(*)`, `Skill(*)`, `WebSearch`, `mcp__github__*`, `mcp__linear__*` (the `linear` server in `.mcp.json`), `mcp__jira__*` (the `jira` server), `Bash(git push --force-with-lease:*)`, `Read(./.env.example)`, `Read(./\*\*/.env.example)`, `WebFetch(domain:…)` per host in the network allowlist (apex + `*.` wildcard) | Blanket-allow shell, skills, tracker MCP, scoped web fetch. Claude evaluates `deny`, then `ask`, then `allow`: an `allow` row never overrides a matching `ask` or `deny`. `--force-with-lease` passes because no `deny` row matches it, not because of its `allow` row; the `.env.example` rows never fire, since `Read(./.env.*)` asks first. Session-conditional: bucket needs workspace trust; `Bash(*)` dropped in auto mode (§ Cloud sessions). |
|
|
1277
|
-
| `ask` | `sudo:*`, `brew install:*`, `(pnpm / npm / bun) publish:*`, `gh repo delete:*`, `gh pr close:*`, `gh release delete:*`; git: `git reset --hard:*`, `git reset \*--hard\*`, `git -\* reset \*--hard\*`, `git clean -fd(x):*`, `git clean -\*f\*`, `git filter-branch:*`, `git checkout -- .:*`, `git checkout \*.`, `git checkout \* . \*`, `git restore .:*`, `git restore \*.`, `git restore \* . \*`, `git stash drop:*`, `git stash clear:*`, `git rebase -i:*`, `git rebase \* -i( \*)`, `git rebase \*--interactive\*`, `git \* --no-verify( \*)`, `git commit -n\*`, `git commit \* -n( \*)`; `Read(./.env)`, `Read(./.env.\*)`, `Read(./\*\*/.env)`, `Read(./\*\*/.env.\*)`, `Read(./.bkit/.env)` | Per-call human confirmation for destructive ops, hook-skipping commits / pushes and secret reads. The `\*` globs catch the same git commands with flags in another order (`git reset -q --hard`, `git clean -df`); a git global option before the subcommand (`git -C dir reset --hard`) is not matched. The `.env` rows are globs, not an enumeration of known filenames
|
|
1421
|
+
| `ask` | `sudo:*`, `brew install:*`, `(pnpm / npm / bun) publish:*`, `gh repo delete:*`, `gh pr close:*`, `gh release delete:*`; git: `git reset --hard:*`, `git reset \*--hard\*`, `git -\* reset \*--hard\*`, `git clean -fd(x):*`, `git clean -\*f\*`, `git filter-branch:*`, `git checkout -- .:*`, `git checkout \*.`, `git checkout \* . \*`, `git restore .:*`, `git restore \*.`, `git restore \* . \*`, `git stash drop:*`, `git stash clear:*`, `git rebase -i:*`, `git rebase \* -i( \*)`, `git rebase \*--interactive\*`, `git \* --no-verify( \*)`, `git commit -n\*`, `git commit \* -n( \*)`; `Read(./.env)`, `Read(./.env.\*)`, `Read(./\*\*/.env)`, `Read(./\*\*/.env.\*)`, `Read(./.bkit/.env)` | Per-call human confirmation for destructive ops, hook-skipping commits / pushes and secret reads. The `\*` globs catch the same git commands with flags in another order (`git reset -q --hard`, `git clean -df`); a git global option before the subcommand (`git -C dir reset --hard`) is not matched. The `.env` rows are globs, not an enumeration of known filenames, because an enumeration silently drops `.env.ci` / `.env.preview` / anything a consumer invents into `defaultMode`. The recursive `./**/` forms cover monorepo `apps/*` and `packages/*`. Shell reads of secret files (`cat .env`) carry no `Bash(...)` row: a command-text glob cannot tell a read from a mention. |
|
|
1278
1422
|
| `deny` | `Bash(rm -rf /\*)`, `Bash(rm -rf ~/\*)`, `Bash(rm -rf $HOME/\*)`, `Bash(chmod -R 777 /:*)`, `Bash(git push --force)`, `Bash(git push --force \*)`, `Bash(git push -f)`, `Bash(git push -f \*)`, `Bash(git push -f\*)`, `Bash(git push \* --force)`, `Bash(git push \* --force \*)`, `Bash(git push \* -f\*)`, `Bash(git push \* +\*)`, `Read(./\*\*/\*.pem)`, `Read(./\*\*/\*.p12)`, `Read(./\*\*/id_rsa)` | Hard-block catastrophic deletes, force-push and private-key reads. Force-push is denied as `--force`, `-f` / an `-f…` cluster, or a `+refspec`, in any argument position. No row is a `--force` prefix: `--force:*` and `--force*` also match `--force-with-lease` and would deny the allowed form. |
|
|
1279
1423
|
|
|
1280
|
-
Shell `curl` / `wget` are
|
|
1424
|
+
Shell `curl` / `wget` are not on the Claude `ask` list. They run under `Bash(*)`, with `deny`, the auto-mode classifier, and the advisory `.claude/hooks/bkit-guardrails.cjs` (PreToolUse, matcher `Bash`) as the backstops. Claude rules match a command prefix, not a URL host, so per-domain allows are inexpressible and the only options are blanket-ask or blanket-allow; blanket-ask forces a prompt on every shell fetch in every mode (a content-scoped `ask` is evaluated before the classifier and beats a matching `allow`), which a cloud session has nobody to answer. `WebFetch(domain:…)` governs the `WebFetch` tool only, never `curl` in `Bash`. Cursor gates by parsed URL host (`bkit-guardrails.cjs`), OpenCode via `curl https://{host}/*` allows layered after a `curl *` ask (command-string glob: trailing flags or extra URLs still match, so it narrows rather than blocks). All four run an allowlisted-host fetch unprompted; on an undeclared host Cursor and OpenCode ask, Claude and Codex emit an advisory instead (Claude to avoid re-adding the prompt, Codex because it cannot prompt).
|
|
1281
1425
|
|
|
1282
|
-
**Shell-as-edit-channel.** `.agents/rules.md` requires edit/write tools for file contents so pre-edit gates see them; `sed -i` and redirects into source files route around every one. `bkit-guardrails.cjs` on Claude,
|
|
1426
|
+
**Shell-as-edit-channel.** `.agents/rules.md` requires edit / write tools for file contents so pre-edit gates see them; `sed -i` and redirects into source files route around every one. `bkit-guardrails.cjs` on Claude, Codex and Cursor flags both. It is advisory and never blocks, because the rule has sanctioned exceptions (generated files, bulk mechanical rewrites, a log line appended to the step's own output file) and bkit's own plan workflow relies on one. Redirects into `/dev/null`, `$GITHUB_ENV`, `/tmp`, and `*.log` are deliberately silent. OpenCode has no script hook, so it is uncovered.
|
|
1283
1427
|
|
|
1284
1428
|
### Cloud sessions — what actually applies
|
|
1285
1429
|
|
|
1286
|
-
`permissions.allow`
|
|
1430
|
+
`permissions.allow` grants capability, and it applies only after the workspace trust dialog, which a cloud (`-p` / SDK) session never shows.
|
|
1287
1431
|
|
|
1288
|
-
|
|
1432
|
+
- **If** the workspace is untrusted → every `allow` row above is ignored, and the sole notice is one stderr line that no cloud session surfaces. `deny` / `ask` still apply.
|
|
1433
|
+
|
|
1434
|
+
`bkit install` writes `projects[<repo path>].hasTrustDialogAccepted` into `~/.claude.json` from the generated setup script (`.claude/bkit-cloud.md` § Setup script), which runs as root, pre-clone, pre-Claude, and is snapshotted. `.claude/hooks/bkit-cloud-bootstrap.sh` re-checks the discovered repo root each session and warns on mismatch.
|
|
1435
|
+
|
|
1436
|
+
Auto mode drops broad allow rules that grant arbitrary code execution: blanket `Bash(*)`, wildcarded interpreters, package-manager run commands, `Agent` / `Monitor` rules. Narrow rows (`Bash(npm test)`) survive. `Bash(*)` is a non-auto-mode mechanism only; auto mode runs on classifier verdicts + `autoMode.environment`. The classifier reads `autoMode` from user / managed settings only, never `.claude/settings.json` / `.claude/settings.local.json`, so the setup script seeds it host-side.
|
|
1289
1437
|
|
|
1290
1438
|
<!-- prettier-ignore -->
|
|
1291
1439
|
| Surface | Non-auto session | Auto-mode session |
|
|
@@ -1297,7 +1445,7 @@ Auto mode **drops** broad allow rules granting arbitrary code execution — blan
|
|
|
1297
1445
|
|
|
1298
1446
|
`.mcp.json` declares the wired tracker's server: `mcpServers.github.url = https://api.githubcopilot.com/mcp/`, `mcpServers.linear.url = https://mcp.linear.app/mcp` or `mcpServers.jira.url = https://mcp.atlassian.com/v2/mcp`. SessionStart hook `bash .claude/hooks/bkit-preflight.sh` runs at every session start.
|
|
1299
1447
|
|
|
1300
|
-
**Anti-pattern:** never `--dangerously-skip-permissions` on host.
|
|
1448
|
+
**Anti-pattern:** never use `--dangerously-skip-permissions` on a host. It is for sandbox CI containers only.
|
|
1301
1449
|
|
|
1302
1450
|
## Workflow Primitives — quick reference
|
|
1303
1451
|
|
|
@@ -1305,91 +1453,48 @@ Inline definitions for workflow-file tokens. Keep synced with workflow bodies.
|
|
|
1305
1453
|
|
|
1306
1454
|
### Workflow commands
|
|
1307
1455
|
|
|
1308
|
-
Mechanical step work runs as `bkit <noun> <verb
|
|
1309
|
-
|
|
1310
|
-
| Contract | Rule |
|
|
1311
|
-
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1312
|
-
| stdout | one JSON object; keys camelCase, matching `status.jsonl` (`parentSha`, `subPlan`). |
|
|
1313
|
-
| stderr | Human log lines, tagged `[bkit-<noun>]`. |
|
|
1314
|
-
| Flags | kebab-case; same name for the same thing everywhere: `--workflow --step --fid --month --sub-plan --attempt --verdict --artifact` (repeatable). |
|
|
1315
|
-
| Exit `0` / `1` / `2` | ok / the answer is no (gate failed, max attempts, lock held) / usage error or missing dependency. |
|
|
1316
|
-
| Exit `3`-`79` | Command-specific; listed in that verb's `--help`. |
|
|
1317
|
-
| Exit `80` / `81` / `82` | Do it via MCP (`runtimeGithubCli=false`) / hand the wait back to the agent turn loop / needs a human. |
|
|
1318
|
-
| Month | `YYYYMM` in UTC. |
|
|
1319
|
-
| `status.jsonl` | design / plan / build / debug: `.worktrees/{FID}/` copy when present, else main checkout. ship: current worktree top (`{WORKTREE_PATH}`). |
|
|
1456
|
+
Mechanical step work runs as `bkit <noun> <verb>` commands. Contract, `{BKIT}` invocation, outdated-bkit advisory, step endings, `{OUTBOX}`, and every noun and verb: `.bkit/cli.md`.
|
|
1320
1457
|
|
|
1321
|
-
|
|
1322
|
-
|
|
1323
|
-
```bash
|
|
1324
|
-
"$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" repo info --fetch
|
|
1325
|
-
```
|
|
1458
|
+
### FID generation
|
|
1326
1459
|
|
|
1327
|
-
|
|
1460
|
+
Step 1 of every phase resolves `FID` before taking the lock (the lock path is `logs/{FID}/.lock`, so it cannot come first), with one `bkit fids resolve --prompt-file --issue --title-file --workflow` call. First hit wins:
|
|
1328
1461
|
|
|
1329
|
-
|
|
1462
|
+
1. Session prompt names it — a `docs/plans/` path carrying it, a `feat/{FID}` branch, or a bare word with a `logs/{word}/` folder.
|
|
1463
|
+
2. Current branch is `feat/{FID}` → that `FID`. With `ISSUE_ID` known, only when the `FID` starts with it (lowercased).
|
|
1464
|
+
3. `ISSUE_ID` known → the feature already logged for that issue (`logs/{issue}-*/`, issue lowercased) in the working tree or on `dev`. Two features for one issue → exit 4 listing both; the prompt must name one.
|
|
1465
|
+
4. Mint: `{ISSUE_ID}-{slug}` (Linear / Jira key lowercased), slug = the first 3 words of the title (else the prompt, else the workflow name) after URLs, tags, `/commands`, stopwords and all-digit words are dropped, ASCII lower. `ISSUE_ID` empty (any tracker, or none wired) → `{branch-suffix}-{slug}`. It has no all-digit word, so no tracker parses it as an issue id.
|
|
1466
|
+
5. Suffix: a minted name whose folder holds a finished run of the workflow takes the first of `{fid}-b`, `{fid}-c`, … whose folder is absent or whose last run of that workflow is IN_PROGRESS (every name used → exit 5). A `FID` from the prompt, branch or logs is never suffixed.
|
|
1330
1467
|
|
|
1331
|
-
|
|
1468
|
+
The format check then runs on the result (exit 1): with `--issue` the FID must embed that issue, else any slug passes. `source` says which link won.
|
|
1332
1469
|
|
|
1333
|
-
|
|
1470
|
+
**Bare number:** no issue on a wired tracker, nothing named, and a prompt whose only content is a bare number (`fix 677`) → exit 9; Step 1 STOPs and tells the user to name the issue as `#N`, its key or its URL; never the Failure Path. `fids parse` logs the same hint without failing.
|
|
1334
1471
|
|
|
1335
|
-
|
|
1336
|
-
| Noun | Verbs | Covers |
|
|
1337
|
-
| --- | --- | --- |
|
|
1338
|
-
| `repo` | `info`, `preflight` | Step 1 owner/repo, branch, behind-`dev` notice, outdated-bkit advisory, `{BKIT}` / `{REPO_ROOT}` / `{OUTBOX_ROOT}`; advisory dispatch-permission preflight |
|
|
1339
|
-
| `fids` | `check`, `parse`, `find` | FID format asserts; marker / branch FID recovery; the feature already logged for an issue (`find --issue`: exit 0 one, 1 none, 4 several) |
|
|
1340
|
-
| `runtime` | `detect`, `row`, `assert` | runtime capability table + `runtime-resolved` row |
|
|
1341
|
-
| `locks` | `acquire`, `release` | per-feature `.lock` |
|
|
1342
|
-
| `workflows` | `start`, `fail`, `handover`, `close`, `promote`, `links` | `workflow-started`; the Failure Path (`fail`: row, rebase abort, lock, sentinels, labels, failure comment; `handover --push` / ship's `--flush`); `close` (compliance grade, `workflow-done`, telemetry, report, artifact links, `--outbox`, `--message` commit; ship's `--flush` lands on dev); design / plan canonical promotion (`promote`) and close links (`links`) |
|
|
1343
|
-
| `worktrees` | `setup`, `remove` | Step 2 worktree create / resume / adopt (`--detect` asks the runtime), copy, install; teardown |
|
|
1344
|
-
| `branches` | `sync`, `push`, `land`, `rebase`, `sync-dev`, `anchor-stamp`, `anchor-read` | docs-from-dev merge, base check, every push, design / plan close landing (squash in a throwaway `origin/dev` worktree pushed as `dev` with backoff retries, else PR squash-merge; audit; local `dev` fast-forward; lock release), Tier-2 rebase resolve, ship's local `dev` fast-forward, anchor block |
|
|
1345
|
-
| `prs` | `open`, `probe`, `merge`, `update-branch`, `checks`, `verbose-ci`, `scan-body`, `cross-check`, `transport-row` | PR create / lookup, squash merge (empty body, `--match-head`, auto-route suffix from `--label`), server-side base refresh, check-rollup classification (green when present and none failed/pending), debug's verbose-CI title, close-transport audit (`transport-row --scan --cross-check`) |
|
|
1346
|
-
| `issues` | `text`, `labels`, `comment` | `ISSUE_TEXT` join + cut, label arithmetic + board payload, comment bodies (MCP posts them) |
|
|
1347
|
-
| `runs` | `wait`, `dispatch`, `gate`, `revalidate`, `context`, `mirror`, `declared` | CI polls, CI-Dispatch Gate (`--file` / `--step` record its row, `--label` the re-trigger suffix), ship merge gate (`--pr` / `--squash-of` heads, `--snapshot`, `--record`), ship Step 9 re-validate, auto Step 1 context, release-PR mirror, CI-workflow presence |
|
|
1348
|
-
| `tests` | `run`, `red`, `green` | deepest-declared `bkit:gate:*` run + saved log + verdict; build test-first: a task's red via `bkit:test:file` (row + test snapshot), a sub-plan's audit report (§ Test-first) |
|
|
1349
|
-
| `status` | `path`, `fold`, `route`, `meta`, `row` | status location, fold, routing state (`route --expect=field=value`), `workflow-meta` rows, typed audit rows the fold skips |
|
|
1350
|
-
| `counters` | `derive`, `rows`, `run`, `route`, `max` | attempt counters (step rows or typed audit rows), run number, `MAX_*` routing (`route --of=<step>:<pos>` derives the value; `--of=<step>,<step>:count` sums several steps) |
|
|
1351
|
-
| `steps` | `done`, `finish`, `verdict`, `gate`, `stub` | `step-done` row + commit; the one-call step ending (§ Step endings); verdict header read; mechanical gate items (placeholders, FID, lock, artifacts, the row's `attempt` / `strategy` / `scope`; `--ref` reads `status.jsonl` as committed on a ref); seeding a versioned artifact with a PENDING header |
|
|
1352
|
-
| `ledgers` | `commit`, `union`, `only-bookkeeping` | path-scoped bookkeeping staging, ledger union, carry-forward check |
|
|
1353
|
-
| `context` | `clamp`, `clamp-log`, `ledger-scan`, `list-blocks`, `run-block`, `finalise` | artifact clamping, plan ledger scan, debug `context-fetch`, `bkit-cloud-bootstrap.sh` provision recipes (`list-blocks` → `provision`) |
|
|
1354
|
-
| `roadmap` | `fold`, `feature`, `mirror` | `docs/roadmap.md` re-render; append a phase's `kind:"feature"` row then re-render (`--strict`: exit 1 when it did not land); build / debug close: the row in the worktree, then on dev through the throwaway landing |
|
|
1355
|
-
| `workstreams` | `parse`, `comment` | design Step 11 advisory comment |
|
|
1356
|
-
| `skills` | `prune` | ship Step 7 skill prune |
|
|
1357
|
-
| `ci` | `slop`, `prose`, `skip-token`, `min-push` | `slop:delta` gate (CI and `.husky/pre-push`; takes the base sha as `--base=` or its one bare argument), `lint:prose` gate (Vale over `--glob=` files), `.husky/pre-push` skip-CI token check, `.husky/pre-push` min-push check (every file the pushed `--ref=`s change matches `bkit.minPushPaths`; exit 0 yes, 1 no, 7 range unreadable) |
|
|
1358
|
-
| `setup` | `protect-main` | `main` branch protection requiring `bkit.capstoneJob` |
|
|
1359
|
-
|
|
1360
|
-
CI check names come from `package.json` `bkit.capstoneJob` (default `bkit-tests-check`) and `bkit.ciWorkflow` (default `bkit-ci.yml`) — no command hard-codes a check, workflow file, or app folder.
|
|
1361
|
-
|
|
1362
|
-
No workflow file calls a script outside a `bkit` command; the slop plugin `bkit-slop-type-suppression.mjs` is a copy-and-own template (`scripts/slop/`). `bkit-cloud.yml` carries its own `MAX_DEV_DISPATCH_ATTEMPTS` env because its guards run before bkit is installed.
|
|
1472
|
+
**Tracker URL:** counts as explicit only when it points into this repo — GitHub `…/{owner}/{repo}/issues/N` or `owner/repo#N` with `owner/repo` matching the `origin` remote (case-insensitive; no `origin` → the URL counts, `owner/repo#N` stays bare); Linear `linear.app/…/issue/KEY` with the `bkit.tracker.linear.team` prefix; Jira `{host}/browse/KEY` with the `bkit.tracker.jira.site` host and the `bkit.tracker.jira.project` prefix. Any other tracker URL is ignored (neither explicit nor bare). An unset `origin` / team / site / project is not compared.
|
|
1363
1473
|
|
|
1364
|
-
|
|
1474
|
+
**Bare key:** Linear / Jira with no `bkit.tracker.linear.team` / `bkit.tracker.jira.project` → a bare `WORD-123` never counts (`SHA-256`, `UTF-8`); explicit forms still do. `fids parse` logs a hint naming the setting when it skipped one and found no issue.
|
|
1365
1475
|
|
|
1366
|
-
|
|
1367
|
-
|
|
1368
|
-
1. Session prompt names it — an `FID` slug, a `feat/{FID}` branch, or a `docs/plans/` path carrying it.
|
|
1369
|
-
2. Current branch is `feat/{FID}`.
|
|
1370
|
-
3. `ISSUE_ID` known → the feature already logged for that issue (`logs/{issue}-*/`, issue lowercased). Two features for one issue → Failure Path listing both; the prompt must name one.
|
|
1371
|
-
4. Mint: `{ISSUE_ID}-{slug}` (Linear / Jira key lowercased), slug = title kebab, stopwords stripped, <=3 tokens, ASCII lower. No tracker → `{branch-suffix}-{slug}`.
|
|
1476
|
+
**Issue from the branch:** no issue in the prompt → `bkit fids parse --branch="feat/{FID}"` takes any lowercase-slug suffix verbatim as `FID` (`feat/upgrade-react-19` → `upgrade-react-19`, no all-digit check). An embedded issue id counts only when `.bkit/issues.jsonl` has a feature row for that FID (Linear / Jira lowercased); else issue-less. A non-slug suffix (`feat/Fix_CI`) exits 3 → Step 1 STOPs and tells the user to rename the branch or name an issue; never the Failure Path.
|
|
1372
1477
|
|
|
1373
1478
|
One FID for all artifacts once set. A workflow never takes `FID` from the newest leftover `.lock` or newest month bucket: on a fresh run with no issue or plan, that silently attached the run to an unrelated feature's logs.
|
|
1374
1479
|
|
|
1375
1480
|
### Branch eligibility
|
|
1376
1481
|
|
|
1377
|
-
`/bkit-debug` Step 2: any branch but `main`.
|
|
1482
|
+
`/bkit-debug` Step 2: any branch but `main`. On `dev` the run works in place: own paths, own commits, no PR; Steps 9 and 10 push nothing; Step 11 pushes the run's commits and gates the dev CI run at the pushed sha before releasing the lock. Exit 10 (a file modified before the run changed during it) writes no row, commits nothing, stops and asks the human, never the Failure Path; the re-run writes each row once. The shared-checkout record is a start snapshot: a path clean at start and edited mid-run by a person is committed as the run's own, because the lock and exit 13 stop parallel bkit runs, not people.
|
|
1378
1483
|
|
|
1379
|
-
`/bkit-ship` Step 2 ships `SHIP_BRANCH` = the branch the prompt names, else `feat/{FID}` when it exists locally or on `origin`, else the session branch when it is not `dev` / `main`, else `feat/{FID}`. `dev` / `main` are refused. A branch not named for `{FID}`
|
|
1484
|
+
`/bkit-ship` Step 2 ships `SHIP_BRANCH` = the branch the prompt names, else `feat/{FID}` when it exists locally or on `origin`, else the session branch when it is not `dev` / `main`, else `feat/{FID}`. `dev` / `main` are refused: `worktrees setup` exits 7 ("refusing to ship ... releases stay manual") → Step 1 releases the lock and STOPs, no Failure Path. A branch not named for `{FID}` (or `{ISSUE_ID}` when one exists) gets a warning, not a stop, because the prompt is the authority on what to ship. Later ship steps (CI dispatch and poll, merge gate, branch cleanup) use `SHIP_BRANCH`, never a hardcoded `feat/{FID}`; cleanup refuses to delete `dev` / `main`.
|
|
1380
1485
|
|
|
1381
1486
|
### Best-effort runs (no issue, no plan)
|
|
1382
1487
|
|
|
1383
1488
|
No phase needs a plan file. A missing plan is flagged, never fatal; only "nothing to act on" stops a run.
|
|
1384
1489
|
|
|
1385
|
-
- **No issue:**
|
|
1386
|
-
- **No plan:**
|
|
1490
|
+
- **No issue:** Step 1 recovers `ISSUE_ID` from a named `FID` or a `feat/{FID}` branch via `bkit fids parse --branch` (a branch id counts only when `.bkit/issues.jsonl` has a feature row for it; a non-slug branch suffix is a STOP); none found → `ISSUE_ID=""`, the no-issue warning (`**No issue:**` header bullet; first line of every final message), and every issue-tied tracker read, label, comment, board call and kill-switch check is skipped (`**Skip if** ISSUE_ID empty`). Workflows never create issues; `/bkit-design` Step 11 needs an issue. `none` → runs without, no warning. Naming the issue-less `FID` in the next prompt is the only way to continue an earlier run (logs and attempt counter continue, as under `none`). A reworded prompt mints a new `FID` and the attempt counter restarts; a minted name whose earlier run finished takes the first free suffix (`{fid}-b`, `{fid}-c`, …) from `bkit fids resolve`, so a repeat never reopens finished logs. A `FID` taken from the prompt or the branch is never suffixed.
|
|
1491
|
+
- **No plan:** build writes one — Step 4 `@bkit-build-plan-convert` turns the session prompt and issue text into `{FID}-plan.md` in task-block form, so every build runs from a plan file. A converted plan carries no `bkit:anchor`, so Plan Current skips (Step 5 `anchor-read` exit 12). Ship: a built FID always has `{FID}-plan.md`; none → Step 5 writes a console warning (the branch was not built by `/bkit-build`) and `ship-input-{RUN}.md` (prompt + issue text) is the plan, never written or ticked; `@bkit-ship-deferred-sweep` takes tasks from its requested outcomes, outcome as worded is the bar.
|
|
1387
1492
|
- **No PR, `/bkit-ship`:** opened by ship when the branch is ahead of `dev`. Red or missing CI on an existing PR still stops ship — it never merges unverified work.
|
|
1388
1493
|
- `/bkit-auto` is out of scope: it is dispatched by CI on an issue label or PR, so an issue or PR always exists.
|
|
1389
1494
|
|
|
1390
1495
|
### Label flip
|
|
1391
1496
|
|
|
1392
|
-
`bkit issues labels` does the label arithmetic and prints the full set; the
|
|
1497
|
+
`bkit issues labels` does the label arithmetic and prints the full set; with `--write` it reads the issue's labels itself, writes the set, the state and the board move, and prints `tracker` / `boardWrite` (`done` = false → the tracker MCP writes the printed set). Without `--write`, pass each current label as `--label=`.
|
|
1393
1498
|
|
|
1394
1499
|
```text
|
|
1395
1500
|
# Phase label (mutually exclusive — drops every other phase label, every next:* and bkit:failed; keeps bkit:auto and foreign ones):
|
|
@@ -1402,90 +1507,117 @@ bkit issues labels --failed=on|off --label=… → `labels` → `issue-update-fa
|
|
|
1402
1507
|
bkit issues labels --label=… → `autoRouteSuffix` → `AUTO_ROUTE_SUFFIX` in the fence that commits or dispatches
|
|
1403
1508
|
```
|
|
1404
1509
|
|
|
1405
|
-
Phase labels (`bkit:design`/`bkit:plan`/`bkit:build`/`bkit:debug`/`bkit:ship`/`bkit:merged`) are mutually exclusive
|
|
1406
|
-
|
|
1407
|
-
### Sub-plan loop discovery
|
|
1408
|
-
|
|
1409
|
-
```bash
|
|
1410
|
-
SUB_COUNT=$(find docs/plans/{YYYYMM} -maxdepth 1 -type f -name '{FID}-plan-*.md' 2>/dev/null | wc -l | tr -d ' ')
|
|
1411
|
-
SINGLE_PLAN=false
|
|
1412
|
-
[ "$SUB_COUNT" -eq 0 ] && SUB_COUNT=1 && SINGLE_PLAN=true
|
|
1413
|
-
# Per N: VERIFY_ATTEMPT derived with `bkit counters derive --sub-plan=N`, so each N starts at 1
|
|
1414
|
-
```
|
|
1510
|
+
Phase labels (`bkit:design`/`bkit:plan`/`bkit:build`/`bkit:debug`/`bkit:ship`/`bkit:merged`) are mutually exclusive: drop the old one before adding the new one. `--phase` also drops every `next:*` label and `bkit:failed` (refuses `--failed=on`), so a started issue carries no stale next-step hint or Failure Path marker. `bkit:failed` skips the drop on its own and lives alongside the phase label. `--board=progress|review` adds the Projects v2 payloads. `trackerState` = the Linear or Jira state the transition moves to: `progress` on a phase start or `--board=progress`, `review` on `bkit:merged`, `bkit:failed` or `--board=review`, named by package.json `bkit.tracker.linear` / `bkit.tracker.jira` `progress` / `review` (defaults `started` / `In Review` on Linear, `In Progress` / `In Review` on Jira); null under github and none.
|
|
1415
1511
|
|
|
1416
1512
|
### Local gate scripts
|
|
1417
1513
|
|
|
1418
1514
|
Workflows, prompts and git hooks name a gate; `package.json` defines it. Never inline a toolchain command at a call site.
|
|
1419
1515
|
|
|
1420
|
-
Each gate is the previous gate plus its own tier, so the name and the value describe the same sequence. Tier names are the `bkit-ci.yml` job ids (`bkit-tests-static` / `-unit` / `-integration` / `-e2e` / `-live`), so a caller reads the coverage off the name and `scope` in `status.jsonl` is self-describing. Where a step is not a tier, the name spells out the step. The consumer owns every value
|
|
1516
|
+
Each gate is the previous gate plus its own tier, so the name and the value describe the same sequence. Tier names are the `bkit-ci.yml` job ids (`bkit-tests-static` / `-unit` / `-integration` / `-e2e` / `-live`), so a caller reads the coverage off the name and `scope` in `status.jsonl` is self-describing. Where a step is not a tier, the name spells out the step. The consumer owns every value: a turbo monorepo writes `turbo run … --filter='...[origin/dev]' --continue`, a Python repo writes `ruff check && pytest`; bkit reads only whether a name is declared.
|
|
1421
1517
|
|
|
1422
1518
|
<!-- prettier-ignore -->
|
|
1423
1519
|
| Gate | Seeded default | Called by |
|
|
1424
1520
|
| --- | --- | --- |
|
|
1425
1521
|
| `bkit:gate:format` | `pnpm lint-staged` | `.husky/pre-commit` |
|
|
1426
|
-
| `bkit:gate:min` | `pnpm format:check && pnpm lint:prose && pnpm slop:delta` | `.husky/pre-push` on a min push |
|
|
1427
|
-
| `bkit:gate:static` | `pnpm typecheck && pnpm lint && pnpm format:check && pnpm lint:prose && pnpm slop:delta` | `@bkit-build-plan-
|
|
1428
|
-
| `bkit:gate:static-unit` | `pnpm bkit:gate:static && pnpm test` | build
|
|
1429
|
-
| `bkit:gate:static-unit-integration` | not seeded — `pnpm bkit:gate:static-unit && pnpm test:integration` | build
|
|
1522
|
+
| `bkit:gate:min` | `pnpm format:check && pnpm bkit:lint:prose && pnpm bkit:slop:delta` | `.husky/pre-push` on a min push; bookkeeping landings through `pushToDev` |
|
|
1523
|
+
| `bkit:gate:static` | `pnpm typecheck && pnpm lint && pnpm format:check && pnpm bkit:lint:prose && pnpm bkit:slop:delta` | `@bkit-build-plan-tasks` (through `bkit tests changed`, when `bkit:gate:changed` is undeclared), `.husky/pre-push` revert path |
|
|
1524
|
+
| `bkit:gate:static-unit` | `pnpm bkit:gate:static && pnpm test` | build Step 8 (group gate), build Step 12 and `.husky/pre-push` (no integration gate declared); `@bkit-build-plan-gaps-remediate`, `@bkit-build-plan-verify` and `@bkit-debug-failure-remediate` (through `bkit tests changed`, when `bkit:gate:changed` is undeclared) |
|
|
1525
|
+
| `bkit:gate:static-unit-integration` | not seeded — `pnpm bkit:gate:static-unit && pnpm test:integration` | build Step 12, debug Step 3, `.husky/pre-push` |
|
|
1430
1526
|
| `bkit:gate:static-unit-integration-e2e` | not seeded — chains the gate above | debug Step 3 |
|
|
1431
1527
|
| `bkit:gate:static-unit-integration-e2e-live` | not seeded — chains the gate above | debug Step 3 |
|
|
1528
|
+
| `bkit:gate:changed` | not seeded — the stack's checks on the files passed as arguments | `bkit tests changed`, run by `@bkit-build-plan-tasks`, `@bkit-build-plan-gaps-remediate`, `@bkit-build-plan-verify` (Holistic) and `@bkit-debug-failure-remediate` |
|
|
1432
1529
|
| `bkit:gate:install-static-unit-build` | `pnpm install --frozen-lockfile && pnpm bkit:gate:static-unit && pnpm build` | `@bkit-ship-conflict-resolve` |
|
|
1433
1530
|
|
|
1434
|
-
|
|
1531
|
+
Gate contents: every gate but `bkit:gate:static-unit-integration-e2e` and `bkit:gate:static-unit-integration-e2e-live` runs on a push or inside `/bkit-build`, so it must not run tests that need a deployed boundary or remote service; local services (a database in Docker) are fine. Those tests go in the two deep gates, which only debug Step 3 runs. bkit cannot check this, because it never reads what a gate runs beyond its seeded default. That is why every gate advisory at install, upgrade and `bkit check` restates it.
|
|
1532
|
+
|
|
1533
|
+
Push gates execute through `bkit ci push-gate --gate=<script>`. It records successful full checks for incremental bookkeeping classification (§ Git hooks in `.bkit/templates.md`). Minimum local validation does not suppress required CI, and workflow test gates retain their declared scope.
|
|
1534
|
+
|
|
1535
|
+
Dependency inspection: `bkit:deps:outdated` / `bkit:deps:audit` exist so prompts stop hardcoding `pnpm outdated` / `pnpm audit`; neither belongs in the table above. CI and pre-push gate: the copy-and-own `Check Dependency Audit` step (`bkit-tests-static`, `scripts/ci/bkit-check-dependency-audit.mjs`) fails on a high / critical advisory without an in-date `scripts/ci/bkit-accepted-advisories.json` acceptance, and the `.husky/pre-push` template runs the same gate above the gates (`deployments.md` § Dependency updaters).
|
|
1536
|
+
|
|
1537
|
+
`bkit:test:file` is not a gate either: it runs one test file (bkit appends the repo-relative path as its argument) and writes a JUnit report to the path in `$BKIT_TEST_REPORT`. `/bkit-build` reads that report for test-first (§ Test-first). It is not seeded, because no default runs one file on every stack; the `test-file-script-missing` advisory (install, `bkit check`, `bkit upgrade`) hands over the line until it is declared. Call the runner directly: a task runner that caches results or runs dependent packages first breaks the one-file contract.
|
|
1538
|
+
|
|
1539
|
+
`bkit:lint:file` lints one test file the same way (path appended, exit 0 when clean). `bkit tests red` runs it on each planned test file before running the file, and a failing lint is a `lint` gap for that file's tests, so the tests step fixes the lint before any red is recorded: a lint rewrite after the red would change the file's blob and `steps finish` would refuse the code step (exit 11). Not seeded; `lint-file-script-missing` advises it once `bkit:test:file` is declared. Undeclared → red skips it and says so.
|
|
1540
|
+
|
|
1541
|
+
`bkit:generate` is not a gate either: it rewrites every generated file and saved baseline (snapshots, coverage lists, generated docs) from the current working tree, in place, so a commit never carries code whose generated output is stale.
|
|
1435
1542
|
|
|
1436
|
-
|
|
1543
|
+
- **Contract:** no arguments; idempotent, so a second run changes nothing; exit 0 on success, non-zero on failure.
|
|
1544
|
+
- **Callers:** `@bkit-build-plan-tasks` and `@bkit-build-plan-gaps-remediate` run it once after their last change, before the step's commit; `bkit branches sync --merge-docs` (build Step 3), `bkit branches sync --merge` (ship Step 4) and `bkit branches push` run it after they merge `origin/dev`; `bkit branches regenerate` runs it in ship Step 10's regenerate round. Each commits only the paths `bkit:generate` changed, so uncommitted work already in the tree stays out, and refuses when it changed a path that already held uncommitted changes.
|
|
1545
|
+
- **Undeclared:** every caller skips it.
|
|
1546
|
+
|
|
1547
|
+
Not seeded, because which files a stack generates is the stack's business. A regenerated baseline is never a `TEST FIRST` test: regenerating it makes it pass, so it cannot fail first.
|
|
1548
|
+
|
|
1549
|
+
`bkit:gate:changed` checks only what an agent step changed, so build and debug agents do not re-run a whole gate after every change. It chains no other gate. `bkit tests changed [--base=<sha>] --fallback=<gate>` computes the changed files and appends them as arguments (repo-relative):
|
|
1550
|
+
|
|
1551
|
+
- **Changed:** every uncommitted file (staged, unstaged, untracked and not ignored), plus every file a commit after `--base` touched. `--base` defaults to `HEAD`, which is the step's start commit because agent steps never commit; `@bkit-build-plan-verify` (Holistic) passes `--base=origin/dev` to cover the whole feature. A deleted file is left out.
|
|
1552
|
+
- **Contract:** run the tests that import the files, the tests that name their paths, and static checks (lint, format, typecheck) on the files; exit 0 when clean.
|
|
1553
|
+
- **No files changed:** nothing runs, exit 0.
|
|
1554
|
+
- **Undeclared:** the `--fallback` gate runs whole, with no arguments: `bkit:gate:static` for `@bkit-build-plan-tasks`, `bkit:gate:static-unit` for the others.
|
|
1555
|
+
|
|
1556
|
+
Not seeded, because finding the tests a file affects is the stack's job; the `gate-changed-script-missing` advisory (install, `bkit check`, `bkit upgrade`) hands over the line until it is declared or named in `bkit.advisories.ignore`. The orchestrator's gates (build Step 8 and Step 12, debug Step 3, `.husky/pre-push`, CI) still run whole gates.
|
|
1437
1557
|
|
|
1438
1558
|
Agents and humans run the same scripts, so a green agent gate and a green `git push` mean the same thing. `bkit-ci.yml` deliberately stays off them: it needs per-step reporting, affected-package conditionals, and the heavier tiers the local gate excludes, so it calls `pnpm typecheck` / `pnpm test` / … directly.
|
|
1439
1559
|
|
|
1440
|
-
`lint:slop` is in no gate
|
|
1560
|
+
`lint:slop` is in no gate, because `slop-scan scan` is report-only and never fails; `bkit:slop:delta` (`bkit ci slop`) is the enforcing gate. `bkit check` (mirror drift) sits in `.husky/pre-push` outside the gates: it validates the bkit install, not consumer source. `bkit:lint:prose` (`bkit ci prose`) scans a whole-repo file set, so it gates at pre-push, not pre-commit.
|
|
1441
1561
|
|
|
1442
1562
|
The three deep gates are not seeded: a seeded `pnpm test:integration` hard-fails every repo without that tier, and a gate named `…-integration-e2e` that skipped them silently is the false-green this design exists to kill. Declaring one — a single line chaining its parent — is how a consumer opts a workflow into a deeper tier.
|
|
1443
1563
|
|
|
1444
|
-
Build and debug each run the deepest gate the consumer declares, and record its name:
|
|
1564
|
+
Build Step 12 and debug each run the deepest gate the consumer declares, and record its name; the build group gate runs `bkit:gate:static-unit` alone (§ Group gate):
|
|
1445
1565
|
|
|
1446
1566
|
<!-- prettier-ignore -->
|
|
1447
1567
|
| Workflow | Candidates, descending | Stops at |
|
|
1448
1568
|
| --- | --- | --- |
|
|
1449
|
-
| build Step
|
|
1450
|
-
| debug Step 3 | `…-integration-e2e-live`, `…-integration-e2e`, `static-unit` | live |
|
|
1569
|
+
| build Step 12 | `static-unit-integration`, `static-unit` | integration |
|
|
1570
|
+
| debug Step 3 | `…-integration-e2e-live`, `…-integration-e2e`, `static-unit-integration`, `static-unit` | live |
|
|
1571
|
+
|
|
1572
|
+
Build stops at integration because its diagnose → remediate loop can only repair what its own gate runs. A tier left to CI is a defect the agent cannot fix in-session (build closes green, the PR reds, recovery is a separate `/bkit-debug`). Integration catches contract breaks the unit tier structurally cannot, at a cost the loop absorbs. E2E does not pay for itself there: it is a production build plus a browser, re-run on every remediation attempt, minutes before CI runs the same thing on the resulting PR. Debug reaches every tier because reproducing the failure is the job.
|
|
1451
1573
|
|
|
1452
|
-
|
|
1574
|
+
Both resolve via `bkit tests run --gate=<deepest> --gate=<next> … --log=`: the deepest declared candidate runs (an empty script is not declared) and its full output is saved to `--log`; `scope` names it. None declared → exit 3, nothing run; a gate that could not run (126 / 127) → exit 4, never a FAIL verdict, so a missing tool is never diagnosed as a failing test. With `--file` (needs `--workflow` and `--step`, and an existing `status.jsonl`) every run, pass, fail or could not run, appends one `test-run` row and prints it as `row`.
|
|
1453
1575
|
|
|
1454
|
-
|
|
1576
|
+
**Failure count from JUnit reports.** `tests run` empties `{log}.reports/` (next to the log, in the outbox, never committed) and passes its absolute path to the gate as `$BKIT_TEST_REPORT_DIR`. `failures` = failing plus erroring test cases summed over every `*.xml` there; skipped cases do not count. PASS prints 0. FAIL with no report, or with reports naming no failing case, prints `null` (count unknown) and a hint — never a guessed number; the step then drops `--failures`. Each test runner in a gate writes its own JUnit file into that folder (`docs/testing.md` § JUnit reports for bkit).
|
|
1455
1577
|
|
|
1456
|
-
A repo with no integration tier is visibly gated at `bkit:gate:static-unit` instead of quietly claiming more. `[live=off]`
|
|
1578
|
+
A repo with no integration tier is visibly gated at `bkit:gate:static-unit` instead of quietly claiming more. `[live=off]` in the session prompt drops debug's live candidate (`status route --prompt-file` prints the remaining `gates`); no live gate declared → CONCERNS + `testsLiveSkipped`.
|
|
1457
1579
|
|
|
1458
1580
|
Build does not run the live tier (post-merge `bkit-tests-live` canary). Every `bkit install` and `bkit upgrade` seeds the missing `bkit:gate:*` names; install also advises on any script they chain that `package.json` does not declare (`.bkit/templates.md` lists those tool scripts). A gate name already present is never touched, whatever its value.
|
|
1459
1581
|
|
|
1460
|
-
###
|
|
1582
|
+
### Group gate
|
|
1461
1583
|
|
|
1462
|
-
Build Step
|
|
1584
|
+
Build Step 8 runs `bkit:gate:static-unit` (static checks and the unit tier) after every group but the last, once `@bkit-build-plan-verify` passes. Red → Step 9 under `build.verify.maxAttempts`, like a verify gap; the next group never starts on a broken tree. The last group skips it, because Steps 10 + 12 follow.
|
|
1463
1585
|
|
|
1464
|
-
- **Orchestrator-owned:** agent gate runs (execute, gaps-remediate, verify) are self-reported in their logs; the
|
|
1465
|
-
- **
|
|
1466
|
-
- **Strict, no exceptions:** a
|
|
1586
|
+
- **Orchestrator-owned:** agent gate runs (execute, gaps-remediate, verify) are self-reported in their logs; the group gate writes a `build-group-gate` row (`verdict`, `scope`), so a skipped gate is visible.
|
|
1587
|
+
- **Unit tier only:** includes the coverage floor where the consumer chains one into `bkit:gate:static-unit`, never integration. Integration runs once, at Step 12, then again at pre-push and in CI before anything merges. Each group gate re-runs the whole suite, so integration there multiplies its cost by the group count, while unit tests import the same code and catch most breaks a later group would hit. Cost: an integration-only break surfaces at Step 12 against the whole diff, fixed by the Steps 13-14 diagnose and fix rounds; the failing test names the area.
|
|
1588
|
+
- **Strict, no exceptions:** the end of a group is where a build can stop (verify budget exhausted, session lost, `/bkit-ship` resume) → it must hold a tree that passes the unit gate. No expected-red declaration. A red gate is an ordering defect (signature change split from callers, deletion before replacement, tests deferred to a later task): `@bkit-plan-generate` orders its groups to keep every group gate green, putting the tasks in one group when it cannot. Add an exception mechanism only once a real case shows a legitimate red group gate.
|
|
1467
1589
|
|
|
1468
1590
|
### Test-first
|
|
1469
1591
|
|
|
1470
|
-
Every plan task carries `**
|
|
1592
|
+
Every plan task block carries a `**TEST FIRST:**` field — one sub-bullet per test, 1 to `package.json` `bkit.workflows.tasks.maxTestsPerTask` tests (default 10) across <= `bkit.workflows.tasks.maxTestFilesPerTask` test files (default 3), each a test file + test name + `fails on {what goes wrong}`, or `n/a — {reason}` (no behaviour change, or E2E / `@live` tier only; plan scope-check rejects an unjustified `n/a`). Build proves each named test failed before its task's code existed, by separation rather than order inside one agent: one subagent writes a group's tests and may touch nothing else, the engine records them red, and only then does another subagent write the group's code and may touch no planned test.
|
|
1471
1593
|
|
|
1472
1594
|
<!-- prettier-ignore -->
|
|
1473
1595
|
| Moment | Who | What is checked |
|
|
1474
1596
|
| --- | --- | --- |
|
|
1475
|
-
|
|
|
1476
|
-
|
|
|
1477
|
-
|
|
|
1478
|
-
|
|
1479
|
-
|
|
1480
|
-
|
|
1481
|
-
- **
|
|
1482
|
-
- **
|
|
1483
|
-
- **
|
|
1484
|
-
- **
|
|
1597
|
+
| Write (Step 7, per group) | `@bkit-build-plan-tests` from `build-brief-tests-{GROUP}-{n}.md`, log `build-plan-tests-{GROUP}-log.md` | Writes every planned test of the group's open tasks that no red row has proved yet, each failing on the behaviour its `fails on` text names, lint-clean; stubs only where a test cannot load without one; no source code. Log lines ``WROTE — TASK {N}: `{file}` `{name}` ``, ``PASSES — TASK {N}: `{file}` `{name}`: {reason}`` (the behaviour already exists), ``BLOCKED — TASK {N}: `{file}` `{name}` — {reason}``, `SOURCE — TASK {N}: {value} from {file}:{line}` (where a value the test checks or fakes comes from). `steps finish --step=build-plan-tests --plan` reads the group's `TEST FIRST` files from the plan and refuses a diff touching any other tracked file, or adding a file a plan `CREATE` line names: exit 15, `source` names them, nothing committed; the orchestrator re-asks once (undo the edits), then Failure Path. |
|
|
1598
|
+
| Red (Step 7, per group) | orchestrator runs `bkit tests red --group`, log `build-tests-red-{GROUP}-{n}.md` | Per planned test file of the group's open tasks: `bkit:lint:file` (when declared) passes on it, then `bkit:test:file` runs it once and its JUnit report is read. Per planned test: `red` (ran and failed), `red-not-loaded` (the file failed to load — an import of unwritten code — and the report holds no case of the file; counts as red), `passed-accepted` (passed, and the writer's log has a `PASSES` line for it; already landed), `updated` (passed, no `PASSES` line, and the test already existed at the group's start commit with different lines: an existing test the tests step changed; `base` = that commit; counts as proven, and verify judges its diff), `vacuous` (passed, no `PASSES` line, not an update), `missing` (absent from a loaded report, or the file does not exist), `no-report` (no report written), `lint` (the file failed lint; not run). Writes one `build-tests-red` row (`attempt`, `enforced`, `tests` = `{task, test, testName, state, blob, block, reason?, base?}`, `blob` the file's git blob written into the object store with `hash-object -w`, `block` the sha-1 of the test's own lines (null when no line names it), `--commit=none`). Exit 0 every test red; 1 a gap; 3 `bkit:test:file` undeclared (blobs recorded, nothing ran, not enforced); 4 a script could not run. A test an earlier row of the group proved (`red`, `red-not-loaded`, `passed-accepted`, `updated`) with its own lines unchanged is not run again (`skipped`), so a handover, a retry or a task added to the group runs only what is left; a row holds the tests it ran, and readers merge the group's rows per test, later rows winning, except that a proven entry stands against a later unproven result for the same lines. Ticked tasks are skipped. Exit 1 → the orchestrator re-invokes the tests agent once with the red report (rewrite only the `vacuous` / `missing` / `no-report` / `lint` tests), runs red again, and then moves on whatever the result: the gaps reach `tests green` as `unproven`. |
|
|
1599
|
+
| Green (Step 8, before verify) | orchestrator runs `bkit tests green` | per planned test: a red entry of the group's rows in a proven state (else listed `unproven`, never a gap, its detail naming the recorded state or that no row exists); `passed-accepted` → `Already landed`, no gap; `updated` → `Updated tests` with the line diff of the test's own lines since `base` and whether it is additive (no line removed), no gap; the named test passes now (else `not-green`). Applies honoured `TEST EXCEPTION` fields; a task whose only test field is a `TEST EXCEPTION` not honoured → `exception-refused`. Per `DELETE` line: the file still exists, or its name (a dotted config key's full path, a `§ heading` as a heading line) is still found in the tree (`git grep`, untracked files included, the plan folder skipped) → `delete-still-referenced`; a `DELETE` + `CREATE` of the same thing is a move, not checked; a file-only `DELETE` + a `CREATE` of the same file name: the new file and paths to it are no reference; a failed grep → the gap says `references not checked`. `--group=N` audits that group's tasks only; a group that is missing or has no tasks → exit 2. Writes `build-tests-green-N-{VERIFY_ATTEMPT}.md` (`Enforced` / `Gaps` / `Unproven` header, `Test exceptions`, `Already landed`, `Updated tests` and `Unproven` sections); prints `alreadyLanded`, `updated` and `unproven`. |
|
|
1600
|
+
| Judgement (Step 8) | `@bkit-build-plan-verify` | `not-green` → `Fixable: true`; `Already landed` and `Unproven` sections → noted, no gap; `Updated tests` → the entry's line diff since `base` read (additive = no line removed; the added lines are still read for one that disables an earlier expectation): it only adds expectations → no gap, else `test-loosened` → `Fixable: true` and the test named on the header's `Loosened` line, or `Fixable: false` when an earlier verify of the group already logged it for that test; `delete-still-referenced` → each hit read: a different thing with the same name → no gap, else `Fixable: true`; `no-test-first`, `test-first-malformed`, `test-first-unread`, `exception-refused` → `Fixable: false`. Each gap logged `— Fixable: true` or `— Fixable: false`; header `Fixable: true` when any gap is. |
|
|
1601
|
+
| Unproven (Step 15) | orchestrator runs `bkit tests green` over the whole plan, log `build-tests-green-final.md` | `unproven` non-empty → one § Decision Pause (`UNPROVEN`), one `Accept` / `Stop` item per test; `Accept` writes a `TEST EXCEPTION`. Asked once per run. |
|
|
1602
|
+
|
|
1603
|
+
- **The report, never the exit code:** a misspelled path, a syntax error, and an import of unwritten code all exit non-zero like a real failure; a test-name filter matching nothing exits 0 with the test skipped. Only the named test's own outcome counts, except that a file that fails to load with no case of its own in the report is `red-not-loaded`: the tests step writes no source, so an import of unwritten code is the expected shape of a red.
|
|
1604
|
+
- **Each planned test case is locked, not its file:** the red row records each planned test file's git blob, written into the local object store (`hash-object -w`) so the content is recoverable while something references it, and each test's `block`: the sha-1 of its own lines. Its lines start on the first line naming it as a quoted string (else as a whole word) that is no comment and opens no suite (`describe`, `context`, `suite`, a class), or on the line before when that line ends with `(`, and run through every deeper-indented line plus one closing line (`}`, `)`, `]`, `end`) at the start's indent; the reader needs only the name and indentation, so it works for any framework. `steps finish` on the code steps (`build-plan-tasks`, `build-plan-gaps-remediate`) re-hashes each planned test of the group and refuses the step when one differs from the block its red recorded: exit 11, `tests` names each `{test, name}`, `touched` their files, nothing committed, `reask` names the agent; the orchestrator re-asks once (put that test back, keep the other edits, or log the task `BLOCKED`), then Failure Path. Each refusal appends an `agent-rework` friction row. Other tests in the same file, helpers and new tests are free to change. A row with no `block` (no line carried the name, or the row predates per-test locking) derives the block from the recorded blob at check time; only when that holds no block either does the check fall back to the whole-file blob.
|
|
1605
|
+
- **Literal names:** the lock finds a test by its name, so a planned test carries its name as a literal string: no `it.each` / `@pytest.mark.parametrize` row and no template string builds it. A plan may name a test by its suite path as a JUnit report does (`suite > test`); red and green match that path as a suffix of the case name, and the lock finds the test by the last `>` segment when no line carries the whole path.
|
|
1606
|
+
- **Updating an existing test:** a `TEST FIRST` line may name a test that already exists (`tests plan-check` lists such names under `existing`, reported only). The tests step may add expectations to it, never remove or loosen one. If it passes after that, the red records it `updated` with the group's start commit as `base`, and verify reads its diff since `base` against that rule. The tests brief lists each such test under `Planned tests that already exist` with the line it starts on (`exists at {file}:{line}`), so the tests step updates it in place rather than writing a second test of that name. A loosened update is `test-loosened`: the first time `Fixable: true`, answered by the tests step (Step 9 sends the test back to it: removed or loosened expectations restored as at `base`, additions kept, the red recorded again, Step 8 re-run), never by the owner or a code step; loosened again → `Fixable: false` → § Decision Pause.
|
|
1607
|
+
- **Resume-safe:** neither step ticks tasks. A resumed or handed-over group re-runs Step 7: the tests brief leaves out every test the group's red rows already proved and names no task with none left, the red skips those tests, the code brief leaves out the `DONE` tasks. A `passed-accepted` test is already landed: `DONE WHEN` already holds with no task code written → execute logs `DONE — TASK N: already landed`; never code undone to force a red.
|
|
1608
|
+
- **Plan caps, `package.json` `bkit.workflows.tasks`:** up to `bkit.workflows.tasks.maxPerGroup` tasks (default 5) and `bkit.workflows.tasks.maxTestsPerGroup` `TEST FIRST` tests (default 25) per group; per task `bkit.workflows.tasks.maxTestsPerTask` tests (default 10) across `bkit.workflows.tasks.maxTestFilesPerTask` test files (default 3). A group is one tests agent's work and then one code agent's work, so the code agent spends no turns on tests and a group carries more tasks than one agent writing both could; a bigger group still overflows a context. A key that is not a whole number >= 1 takes its default, and `bkit check` reports advisory `bkit-tasks-invalid`. `.github/ISSUE_TEMPLATE/bkit-change.yml` showing a key as `(default N)` with N other than the value `readBkitConfig` gives → advisory `bkit-tasks-form-stale`, naming the number to change in the form. Install and upgrade write the defaults when `tasks` or a key in it is missing; a value already set is never touched. `readBkitConfig` reads them (`CONFIG_DEFAULTS.tasks` in `settings.ts`); `tests plan-check` and `challenge merge` read the checkout's caps and refuse a plan over any cap, naming the task or group, its count and the cap; `repo info` prints them as `tasks`, which `/bkit-plan` and `/bkit-build` Step 1 hold as `{MAX_TASKS_PER_GROUP}`, `{MAX_TESTS_PER_GROUP}`, `{MAX_TESTS_PER_TASK}`, `{MAX_TEST_FILES_PER_TASK}` and pass in Context to every agent that writes, reviews, executes or verifies the plan: plan-generate, plan-review-1, plan-review-2, plan-scope-check, plan-update, convert, plan-tests, plan-execute, plan-verify and the challenge reviewers. Prompts name no cap value of their own; each uses the caps its Context names.
|
|
1609
|
+
- **One block reader:** `tests green`, `tests plan-check`, `challenge merge` and the run facts read a plan with `parsePlanBlocks` (`plan-blocks.ts`). A task group is `<!-- bkit:group N start -->`, `### TASK GROUP N: {title}` (`### GROUP N: {title}` is read too) … `<!-- bkit:group N end -->`; a task is `<!-- bkit:task N start -->`, `- [ ] **TASK N:** {title}` … `<!-- bkit:task N end -->` inside a group, its number unique across the plan, its fields uppercase `**LABEL:**` lines. Group numbers start at 1 and ascend through the file (the build runs groups in file order); task numbers start at 1 and ascend within a group, so a Decision Pause task numbered above the plan's highest can join its paused group. `DEPENDS ON`, `DONE WHEN`, `TEST FIRST` and `TEST EXCEPTION` are written once per task; a second one, or a bold `**TASK N:**` line inside another task's block, is refused. `DEPENDS ON: none (...)` names no task; `tests plan-check` refuses a task depending on itself, on a missing task or on a task in a later group. The readers beside it — `reuseInventory`, `derivedTestMatrix` (its `Task` column) and `supersessionInventory` — read the plan's `Reuse Inventory`, `Derived Test Matrix` and `Supersession Inventory` tables; a `CREATE` with no new row, a matrix row naming no task / an undefined task / two tasks or a test-bearing task no row names, and a `DELETE` with no `Supersession Inventory` row are each plan-check problems. CRLF reads like LF. A code fence never closed → `the code fence at line N is never closed; nothing after it is read`. Task-like text outside every block (a bold `task N` in any letter case, a bold field label; inline code and fenced blocks are prose) is a plan-level problem: `tests plan-check` refuses it, and `tests green` reports it as a `test-first-unread` gap (`task` null, `Fixable: false`) while auditing every task it could read.
|
|
1610
|
+
- **`fails on {what goes wrong}`, not an assertion:** a literal assertion can be one current code never passes (a value the path always prints) → the tests step writes a test no code could satisfy. A described failure leaves the tests step free to write a passable check; plan review-2 flags checks current code rules out.
|
|
1611
|
+
- **Unproven tests are asked once, at the end:** a planned test with no proven red (the tests step left it `vacuous`, `missing`, `no-report` or `lint`, or no red row names it) is no gap and stops nothing mid-run: `tests green` lists it as `unproven`, and Step 15 asks the owner once about all of them (§ Decision Pause, `UNPROVEN`). Ship asks again for any accepted headless. An `Accept` writes a `TEST EXCEPTION`, committed on the branch the build runs on — `feat/{FID}` in mint mode, never a separate `dev` commit.
|
|
1612
|
+
- **TEST EXCEPTION:** the only way out. A `**TEST EXCEPTION:**` field inside the task's block in the plan the build reads, tests named as in `TEST FIRST`, committed alone — by the human, or by the build orchestrator ONLY after explicit human approval in a Decision Pause. `tests green` blames the field's lines: honoured only when all are committed and their last commit does not touch the run's `status.jsonl`. Every workflow step commit writes it, so a line riding a step commit is refused. Subagents never commit; one breaking that rule with a commit of the plan alone would pass this check. The tests step writes no test the field names and the red skips them, so a re-run reaches the audit. Honoured → the named tests leave the `unproven` list for the report's cleared list; `not-green` never clears. Refused → report says why; the tests stay `unproven`. A task whose only test field is a `TEST EXCEPTION` (no `TEST FIRST`) gets the same blame check: honoured → its test-first check clears; refused → one `exception-refused` gap, `Fixable: false`, so verify fails and the build reaches the Decision Pause. A plain `TEST FIRST: n/a — {reason}` is not blamed. An issue's `TEST EXCEPTION` = a request: the repo can be public, so an issue author is not necessarily the owner; convert and plan-generate copy it word for word and never write their own, the copy rides their step commit and is refused, and the owner's Decision Pause Accept rewrites it with the owner's reason and date in a plan-alone commit.
|
|
1613
|
+
- **Already landed:** a planned test that passes before the group's code exists, with a `PASSES — TASK N: {file} {name}: {reason}` line in the tests step's log, is recorded `passed-accepted` with that reason; `tests green` lists it under `Already landed` and raises no gap, and execute logs its task `DONE — already landed` when `DONE WHEN` already holds. A pass with no such line is `vacuous` (or `updated`, for an existing test the tests step changed): for `vacuous` the tests step is re-asked once, then the test stays `unproven` until Step 15.
|
|
1614
|
+
- **Not enforced, never silent:** no `bkit:test:file` → `tests red` exits 3 and records the blobs with `enforced` false, `tests green` exits 0 with `Enforced: false` and the reason; verify notes it. No plan file, or a plan with no task markers → exit 1, `Enforced: false`, reason `this plan has no task markers; run /bkit-build again to convert it`: an old-format plan is never passed unaudited; `bkit check` lists such plans of unshipped FIDs as advisory `plan-task-markers-missing`.
|
|
1485
1615
|
|
|
1486
1616
|
### Tracker issue-create return guard
|
|
1487
1617
|
|
|
1488
|
-
When tracker call creates issue, MUST return non-empty `id`.
|
|
1618
|
+
When a tracker call creates an issue, it MUST return a non-empty `id`.
|
|
1619
|
+
|
|
1620
|
+
- **If** it is empty / null → Failure Path `Tracker issue create returned no id`.
|
|
1489
1621
|
|
|
1490
1622
|
### Pre-worktree carry-over commit (Step 2 of design / plan / build)
|
|
1491
1623
|
|
|
@@ -1495,7 +1627,7 @@ When tracker call creates issue, MUST return non-empty `id`. Empty/null → Fail
|
|
|
1495
1627
|
|
|
1496
1628
|
Carries workflow log + ledger rows into the new worktree branch. `--only-if-dirty-tracked` does nothing unless a tracked file is dirty (`outcome` = `clean`); untracked files alone never trigger it. Every site passes `--root` = the main checkout explicitly, so the commit never runs wherever the shell happens to be (a subfolder or another checkout). `/bkit-ship` and `/bkit-debug` omit the primitive.
|
|
1497
1629
|
|
|
1498
|
-
|
|
1630
|
+
Use an allow-list, never a deny-list, because a deny-list on the main checkout is `git add -A` by another name. The pathspec rides `git add` and `git commit`, because a bare `git commit` commits the whole index and sweeps in user-staged work, which then takes a `git revert` to undo. A dirty tree with no bookkeeping in it is `nothing-to-commit`, not an error. Close on main (`design`/`plan`, `--squash-of`) and `/bkit-ship` (`--scope=pr` pre-merge, `--scope=full` close and Failure Path) stage through the same command and allow-list (§ Telemetry Ledgers — Ledger sweep).
|
|
1499
1631
|
|
|
1500
1632
|
## File path conventions
|
|
1501
1633
|
|
|
@@ -1504,9 +1636,8 @@ Allow-list, never deny-list: deny-list on main checkout = `git add -A` by anothe
|
|
|
1504
1636
|
| --- | --- |
|
|
1505
1637
|
| Worktree | `.worktrees/{FID}/` (gitignored) |
|
|
1506
1638
|
| Design draft | `docs/plans/{YYYYMM}/{FID}-design.md` |
|
|
1507
|
-
| Plan draft | `docs/plans/{YYYYMM}/{FID}-plan.md`
|
|
1508
|
-
| Plan active | `docs/plans/{YYYYMM}/{FID}-plan*.md` (
|
|
1509
|
-
| Plan completed | `docs/plans/{YYYYMM}/{FID}-plan*.md` (moved here in `/bkit-ship` Step 9) |
|
|
1639
|
+
| Plan draft | `docs/plans/{YYYYMM}/{FID}-plan.md` |
|
|
1640
|
+
| Plan active / completed | `docs/plans/{YYYYMM}/{FID}-plan*.md` (no move; `{YYYYMM}` = creation month) |
|
|
1510
1641
|
| Superseded design / plan | `docs/plans/{YYYYMM}/archive/{TIMESTAMP}-{FID}-design.md`, `…-{FID}-plan*.md` (moved here by design / plan close on re-run; reachable by no workflow glob) |
|
|
1511
1642
|
| Workflow logs | `docs/plans/{YYYYMM}/logs/{FID}/*.md` |
|
|
1512
1643
|
| Workflow state | `docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` (on `feat/{FID}` for `design`/`plan`/`build`/`debug` + every `ship` step, reaching `dev` via squash-merge or ship's close commit; `cloud` writes none — stateless dispatcher; see § status.jsonl) |
|
|
@@ -1517,43 +1648,35 @@ Allow-list, never deny-list: deny-list on main checkout = `git add -A` by anothe
|
|
|
1517
1648
|
|
|
1518
1649
|
## Loop context accumulation
|
|
1519
1650
|
|
|
1520
|
-
Verify→remediate and diagnose→fix loops carry context
|
|
1651
|
+
Verify→remediate and diagnose→fix loops carry context through per-attempt log files, not plan mutation. Plan docs hold deliverables only.
|
|
1521
1652
|
|
|
1522
1653
|
<!-- prettier-ignore -->
|
|
1523
1654
|
| Verifier / checker | Remediator | Max attempts | Escalation |
|
|
1524
1655
|
| --- | --- | --- | --- |
|
|
1525
|
-
| `@bkit-build-plan-verify` | `@bkit-build-plan-gaps-remediate` | `
|
|
1526
|
-
| `@bkit-build-challenge-
|
|
1527
|
-
| Build test loop (`bkit tests run`, deepest declared gate) | `@bkit-debug-failure-diagnose` → `@bkit-debug-failure-remediate` | `
|
|
1528
|
-
| Debug test loop | `@bkit-debug-failure-diagnose` → `@bkit-debug-failure-remediate` (NORMAL); `@bkit-debug-failure-soak` (SOAK) | `
|
|
1529
|
-
| Ship merge loop | `@bkit-debug-failure-diagnose` → `@bkit-debug-failure-remediate` | `
|
|
1656
|
+
| `@bkit-build-plan-verify` | `@bkit-build-plan-gaps-remediate` | `build.verify.maxAttempts` (2) rounds per group, never reset; unfixable gaps or no progress → Decision Pause | Further rounds taken without asking; limit used up → Decision Pause on the open gaps with the loop question when `ask` is true in a session (a go-on answer grants one more allowance), else Failure Path |
|
|
1657
|
+
| `bkit challenge gate` → `@bkit-build-challenge-2`, plus `@bkit-build-challenge-1` when large (parallel) → `bkit challenge merge` | `@bkit-build-plan-tasks` (the merged findings are plan tasks) | `build.challenge.maxAttempts` (2) rounds (`CHALLENGE_ROUND`): earlier rounds may fix on their own; the last never does | `**Fixable:** false` tasks, last-round tasks, or too many findings → Decision Pause; the last round's fixes are not challenged again |
|
|
1658
|
+
| Build test loop (`bkit tests run`, deepest declared gate) | `@bkit-debug-failure-diagnose` → `@bkit-debug-failure-remediate` | `build.tests.maxAttempts` (2) test rounds, never reset | Further rounds taken without asking; Decision Pause (`TESTS_LOOP`) only when `trend` is `stuck` or `worse`; limit used up → the same pause when `ask` is true in a session (a go-on answer grants one more allowance), else Failure Path |
|
|
1659
|
+
| Debug test loop | `@bkit-debug-failure-diagnose` → `@bkit-debug-failure-remediate` (NORMAL); `@bkit-debug-failure-soak` (SOAK) | `debug.fix.maxAttempts` (2) then `debug.soak.maxAttempts` (2), each counted across every debug run of the feature | Further attempts taken without asking; Loop Question only when `trend` is `stuck` or `worse`; fix used up → SOAK; soak used up → Loop Question when `debug.soak.ask` is true in a session (`Try again` grants one more allowance), else Failure Path with `@bkit-debug-abort-handover` |
|
|
1660
|
+
| Ship merge loop | `@bkit-debug-failure-diagnose` → `@bkit-debug-failure-remediate` | `ship.merge.maxAttempts` (2) failed arrivals at Step 10 (gate refusals plus failed merges) | Fix round taken without asking when the diagnosis verdict is `PASS`, else asked; limit used up → the Merge Question when `ship.merge.ask` is true in a session (`Try again` grants one more allowance), else Failure Path with `@bkit-debug-abort-handover` |
|
|
1530
1661
|
|
|
1531
|
-
**Filename convention:** `docs/plans/{YYYYMM}/logs/{FID}/{phase}-{step}-N-{ATTEMPT}.md` (e.g. `build-verify-
|
|
1662
|
+
**Filename convention:** `docs/plans/{YYYYMM}/logs/{FID}/{phase}-{step}-N-{ATTEMPT}.md` (e.g. `build-plan-verify-1-2.md` = group 1, verify attempt 2). Verifiers must read prior verify+remediate logs before PASS/FAIL. Remediators must glob their own prior logs and must not repeat a strategy.
|
|
1532
1663
|
|
|
1533
1664
|
## Structured Docs Writer Map
|
|
1534
1665
|
|
|
1535
|
-
Pipeline writes structured ledgers at `docs/` root
|
|
1536
|
-
|
|
1537
|
-
<!-- prettier-ignore -->
|
|
1538
|
-
| Doc | Dedup id | Sole writer(s) | Source step |
|
|
1539
|
-
| --- | --- | --- | --- |
|
|
1540
|
-
| `docs/knowledge.jsonl` | `key` | `@bkit-build-plan-gaps-remediate`, `@bkit-build-challenge-remediate`, `@bkit-debug-failure-remediate` | After verified fix |
|
|
1541
|
-
| `docs/decisions.jsonl` | `key` | `@bkit-debug-failure-remediate` (forced arch) | At decision time — the design phase reads ADRs, never authors them |
|
|
1542
|
-
| `.bkit/issues.jsonl` | `key` (the FID) | design / plan / build / debug closes; ship Step 6 (worktree, rides the PR) | Every close / ship Step 6 |
|
|
1543
|
-
| `docs/deferrals.jsonl` | `key` | `@bkit-design-generate` (out-of-scope features), `@bkit-plan-generate` (out-of-scope ideas), `@bkit-plan-update` (scope expansions from `/bkit-plan` Step 8), `@bkit-debug-abort-handover` (handover context), `@bkit-ship-deferred-sweep` (adjudication — same-`key` `reason` = `unjustified`) | `/bkit-design` Step 5, `/bkit-plan` Steps 3 & 8, `/bkit-ship` Step 5, Failure Path handover |
|
|
1666
|
+
Pipeline writes structured ledgers at `docs/` root and `.bkit/`. The exhaustive writer list per ledger kind → `.bkit/jsonl.md` § Ledgers & Writers.
|
|
1544
1667
|
|
|
1545
|
-
All other agents
|
|
1668
|
+
All other agents record blockers / out-of-scope items in their own log file (Plan Execution / Challenge Remediation / etc; each subagent's H1 gives the canonical output name). The workflow reads them at step boundaries and decides what to mirror to the tracker.
|
|
1546
1669
|
|
|
1547
1670
|
Append-only. Row format: `.bkit/jsonl.md`. Doc index + read-by-phase matrix: `.agents/docs.md`.
|
|
1548
1671
|
|
|
1549
1672
|
## Telemetry Ledgers
|
|
1550
1673
|
|
|
1551
|
-
bkit emits JSONL telemetry to six append-only ledgers. Row format (
|
|
1674
|
+
bkit emits JSONL telemetry to six append-only ledgers. Row format (top section, per-kind fields, dedup tuples, write idiom): `.bkit/jsonl.md`.
|
|
1552
1675
|
|
|
1553
1676
|
<!-- prettier-ignore -->
|
|
1554
1677
|
| File | Kind(s) | Scope |
|
|
1555
1678
|
| --- | --- | --- |
|
|
1556
|
-
| `.bkit/stats.jsonl` | `compliance`, `outcome`, `counter` | Per-run/per-workflow stats, compliance grades, counters |
|
|
1679
|
+
| `.bkit/stats.jsonl` | `compliance`, `outcome`, `counter` | Per-run / per-workflow stats, compliance grades, counters; `bkit stats` reports them into `.bkit/stats.md` |
|
|
1557
1680
|
| `.bkit/friction.jsonl` | `friction` | Friction entries from workflow runs |
|
|
1558
1681
|
| `docs/deferrals.jsonl` | `deferral` | Deferred work items and scope-expansions |
|
|
1559
1682
|
| `docs/failures.jsonl` | `failure` | Discovered bugs and failures |
|
|
@@ -1562,6 +1685,7 @@ bkit emits JSONL telemetry to six append-only ledgers. Row format (envelope, per
|
|
|
1562
1685
|
|
|
1563
1686
|
Orchestrator behavior:
|
|
1564
1687
|
|
|
1688
|
+
- **Append route:** `bkit ledgers append --ledger=… --rows=…` writes `decision` / `deferral` / `failure` / `knowledge` / `friction` rows (`--ledger=stats`: `compliance` / `counter` / `outcome`); sets `schema: 3`, mints `ts`, fills `repo` (when absent) / `bkit.version`, refuses the whole batch on one bad row (`.bkit/jsonl.md` § Write Idiom). Every row carries `by: {workflow?, step, subagent?, model?}` (`.bkit/jsonl.md` § Who Wrote It).
|
|
1565
1689
|
- **Never-drop:** never silently drop deferred work → append `kind:"deferral"` to `docs/deferrals.jsonl`.
|
|
1566
1690
|
- **Found-bug:** never silently drop discovered bug → append `kind:"failure"` to `docs/failures.jsonl` immediately.
|
|
1567
1691
|
- **Path idiom (all JSONL ledgers):** resolve once per bash block:
|
|
@@ -1569,37 +1693,37 @@ Orchestrator behavior:
|
|
|
1569
1693
|
- `WT=$(git rev-parse --show-toplevel)` — current write tree (worktree while on `feat/{FID}`; main after `cd "$REPO_ROOT"`). When the block only uses `git -C "$REPO_ROOT"`, set `WT="$REPO_ROOT"` (same tree).
|
|
1570
1694
|
- `STATUS="$WT/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl"`
|
|
1571
1695
|
- `STATS="$WT/.bkit/stats.jsonl"` · `FRICTION="$WT/.bkit/friction.jsonl"`
|
|
1572
|
-
- `docs/{deferrals,failures,knowledge,decisions}.jsonl` → `"$WT/docs/…"`.
|
|
1573
|
-
- **Friction/stats:** `bkit workflows close` appends the `counter` + `outcome` rows to `.bkit/stats.jsonl` (`counterRow` / `outcomeRow`,
|
|
1574
|
-
- **Close commit pathspec:** design / plan on main: `bkit ledgers commit --squash-of=feat/{FID}` (bookkeeping allow-list + the squashed paths). Ship: `bkit ledgers commit --scope=full`. Build/debug (worktree sandbox): `git add -A` after writes — includes the same relative paths under `$WT`.
|
|
1575
|
-
- **Ledger sweep (every path-scoped staging site):** the `{FID}`/`{YYYYMM}` log-dir entry names one feature and one month bucket
|
|
1696
|
+
- `docs/{deferrals,failures,knowledge,decisions}.jsonl` → `"$WT/docs/…"`. Never mix `$REPO_ROOT` and `show-toplevel` for the same ledger in one block.
|
|
1697
|
+
- **Friction / stats:** `bkit workflows close` appends the `counter` + `outcome` rows to `.bkit/stats.jsonl` via `bkit ledgers append --ledger=stats` (`counterRow` / `outcomeRow`); every row of the run carries `run.parentSha` = HEAD at close, also on its `workflow-done` status row. Close's CI dispatch (`bkit runs dispatch`) re-appends the outcome: dispatch added to `ci`, `ending` `close-failed` when CI never started; newer row supersedes under fold. Stage into the close commit that pushes (never leave dirty after push).
|
|
1698
|
+
- **Close commit pathspec:** design / plan on main: `bkit ledgers commit --squash-of=feat/{FID}` (bookkeeping allow-list + the squashed paths). Ship: `bkit ledgers commit --scope=full`. Build / debug (worktree sandbox): `git add -A` after writes — includes the same relative paths under `$WT`.
|
|
1699
|
+
- **Ledger sweep (every path-scoped staging site):** the `{FID}`/`{YYYYMM}` log-dir entry names one feature and one month bucket. A `status.jsonl` under any other bucket, and any ledger added after the list was written, would be appended to, never staged, and lost at the next `git worktree remove --force` / branch switch / clean. `bkit ledgers commit` therefore carries `docs/plans/*/logs/*/*.jsonl docs/*.jsonl .bkit/*.jsonl` (plus `docs/roadmap.md`) in its own pathspec set alongside the log-dir entry, and passes the whole set to `git ls-files`. Git expands the globs itself, so an unmatched glob is empty output (exit 0), never a zsh abort and never shell word-splitting. Sweep root = `--root=` (`$REPO_ROOT` pre-worktree, `$WT` at close, `$BOOK_ROOT` in ship Step 1 / **Failure Path**). The sweep is bounded to those three globs on purpose, because a repo's own `*.jsonl` data or fixtures must never ride into a `[skip ci]` bookkeeping commit. The `-A` ban stays. Ship's worktree→`BOOK_ROOT` reconciliation (`bkit ledgers union`) unions the same swept set row-wise (append-only NDJSON, never copy over; never `.bkit/issues.jsonl`).
|
|
1576
1700
|
- **Best-effort:** telemetry never gates workflow. `bkit workflows close` logs a failed stats append and continues (`telemetryWritten` false); the remaining inline appends (feature rows, ship audit rows) keep `… || echo "[bkit-roadmap] append failed: $FILE"`.
|
|
1577
1701
|
- **Tracker comment:** the close comment carries `bkit workflows close`'s `report` lines (this run vs `med·5` — median of prior 5 same-workflow runs) and `artifactLinks`; telemetry is written once, by `close`, never re-appended after push. `> 5000` rows in `stats.jsonl` → `[bkit-telemetry] WARNING: MAX_ROWS_BEFORE_ROLLUP (5000) exceeded`.
|
|
1578
1702
|
- **Compliance:** `bkit workflows close` grades the run itself (`gradeCompliance`, fail-open) before it writes the report and before its commit, so the close report carries this run's grade and the `kind:"compliance"` rows land in the close commit; `close` prints `compliance` (the violation count, null when the grader was unavailable). Ship's close grades from the parent of `--squash-sha`: the whole feature, not its last commit only. No workflow calls `bkit comply`.
|
|
1579
|
-
- **
|
|
1703
|
+
- **Stray allow-list (design / plan squash):** `^docs/plans/|^docs/roadmap\.md$|^docs/[^/]+\.jsonl$|^\.bkit/[^/]+\.jsonl$`. It must admit everything the ledger sweep can stage. `docs/roadmap.md` needs its own alternative: it is the one staged path that is not a `.jsonl`.
|
|
1580
1704
|
- **Pre-worktree allow-list:** `bkit ledgers commit --scope=core` — `docs/plans/{YYYYMM}/logs/{FID}/`, `.bkit/friction.jsonl`, `.bkit/stats.jsonl`, plus the ledger sweep.
|
|
1581
1705
|
|
|
1582
1706
|
## Authoring Checklist for New / Refined Workflows
|
|
1583
1707
|
|
|
1584
|
-
When writing/editing `.bkit/core/workflows/bkit-*.md` (canonical — `bkit install` regenerates `.claude/commands/` + `.cursor/commands/`):
|
|
1708
|
+
When writing / editing `.bkit/core/workflows/bkit-*.md` (canonical — `bkit install` regenerates `.claude/commands/` + `.cursor/commands/`):
|
|
1585
1709
|
|
|
1586
1710
|
- [ ] YAML frontmatter with `description`.
|
|
1587
1711
|
- [ ] Header with `Output:` and `Tracker:` lines.
|
|
1588
|
-
- [ ]
|
|
1712
|
+
- [ ] Protocol, Contract and Rules blocks with every header bullet (§ Common Workflow Anatomy → Header bullets).
|
|
1589
1713
|
- [ ] **Failure Path** before Step 1; conditional handover branch when phase has retry loops.
|
|
1590
1714
|
- [ ] **Step 1 — Start Workflow:** `bkit repo info` + FID + `bkit locks acquire` + tracker init + comment create + label set + state `In Progress`.
|
|
1591
1715
|
- [ ] **Step 2 — Worktree Setup:** `bkit worktrees setup` + `bkit workflows start --lock-held` + `bkit runtime row` + save phase input + status step + comment append.
|
|
1592
|
-
- [ ] Every bash block calls `"{BKIT}" <noun> <verb>` (Step 1's first block: the lookup expression;
|
|
1593
|
-
- [ ] Every step that writes a row ends in one `bkit steps finish`; a gate without one runs `bkit steps gate`; gate checklists
|
|
1716
|
+
- [ ] Every bash block calls `"{BKIT}" <noun> <verb>` (Step 1's first block: the lookup expression; `.bkit/cli.md`); model values reach commands as flag values, never shell variables; no template-script call, no package-manager literal.
|
|
1717
|
+
- [ ] Every step that writes a row ends in one `bkit steps finish`; a gate without one runs `bkit steps gate`; gate checklists remind in general words, never restate a step detail or what those calls check (§ Gates).
|
|
1594
1718
|
- [ ] Every step ends with `### 🔒 Gate N` and a checklist.
|
|
1595
1719
|
- [ ] Every step appends one fenced section to the workflow comment via the `comment-post-step` tracker snippet (one new comment per step — no COMMENT_ID threading).
|
|
1596
|
-
- [ ] Subagent invocations use `@name` + `Context:` / `Read:` / `Update:` / `Create:` block (Update/Create as applicable); assert non-empty Update/Create artifacts.
|
|
1720
|
+
- [ ] Subagent invocations use `@name` + `Context:` / `Read:` / `Update:` / `Create:` block (Update / Create as applicable); assert non-empty Update / Create artifacts.
|
|
1597
1721
|
- [ ] Verdict-bearing steps extract `{*_VERDICT}` and route per § `Verdict` vocabulary.
|
|
1598
|
-
- [ ] Counters
|
|
1722
|
+
- [ ] Counters derived per fenced block from `status.jsonl` (§ Attempt counters); no prose `Init`/`Increment`; limits by ask point (`bkit counters route --point=`); loops → Failure Path; logs `-{N}`.
|
|
1599
1723
|
- [ ] Timeout guard captures `STEP_START` before each subagent / `bkit tests run`; exceeded → Failure Path.
|
|
1600
1724
|
- [ ] Final step (Close Workflow) runs `bkit workflows close`, releases `.lock` (`bkit locks release --token=`), sets state `In Review` (ship: also swaps `bkit:ship` → `bkit:merged` via `bkit issues labels --phase=merged`); non-ship phases update state only, phase label unchanged.
|
|
1601
1725
|
- [ ] Docs-only commits include `bkit [skip ci]` (§ CI / Vercel commit tags).
|
|
1602
1726
|
- [ ] Branch eligibility check on phases that don't create their own branch (`/bkit-debug`, `/bkit-ship`).
|
|
1603
|
-
- [ ] Token efficient
|
|
1727
|
+
- [ ] Token efficient per `.agents/rules.md` `Format`; `→` not `then`, no sub-bullets when a table works.
|
|
1604
1728
|
- [ ] If new agent is introduced, add it to `.bkit/prompts.md` with frontmatter rationale and `maxTurns` calibration.
|
|
1605
1729
|
- [ ] If new destructive shell command is introduced, route it through `ask` or `deny` in `.claude/settings.json`.
|