@cbartens/bkit 6.1.0 → 6.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +14 -12
- package/.bkit/core/.agents/docs.md +1 -11
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
- package/.bkit/core/.agents/rules.md +22 -9
- package/.bkit/core/.bkit/README.md +13 -11
- package/.bkit/core/.bkit/authoring.md +58 -13
- package/.bkit/core/.bkit/cli.md +43 -33
- package/.bkit/core/.bkit/cloud.md +93 -30
- package/.bkit/core/.bkit/install.md +55 -16
- package/.bkit/core/.bkit/jsonl.md +24 -7
- package/.bkit/core/.bkit/pipeline.md +8 -8
- package/.bkit/core/.bkit/prompts.md +160 -43
- package/.bkit/core/.bkit/providers.md +99 -36
- package/.bkit/core/.bkit/templates.md +167 -37
- package/.bkit/core/.bkit/trackers.md +39 -6
- package/.bkit/core/.bkit/workflows.md +344 -136
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
- package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
- package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/docs/templates/bkit-plan.md +38 -8
- package/.bkit/core/engine/checks/after/auth.ts +118 -47
- package/.bkit/core/engine/checks/after/github.ts +161 -37
- package/.bkit/core/engine/checks/after/index.ts +18 -3
- package/.bkit/core/engine/checks/after/tools.ts +245 -1
- package/.bkit/core/engine/checks/before/files.ts +59 -1
- package/.bkit/core/engine/checks/before/index.ts +8 -0
- package/.bkit/core/engine/checks/status-holes.ts +20 -26
- package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
- package/.bkit/core/engine/checks/tips/detect.ts +36 -3
- package/.bkit/core/engine/checks/tips/index.ts +1 -1
- package/.bkit/core/engine/cli.ts +13 -13
- package/.bkit/core/engine/commands/ci/ci.ts +124 -19
- package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
- package/.bkit/core/engine/commands/install/doctor.ts +5 -5
- package/.bkit/core/engine/commands/install/install.ts +28 -25
- package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
- package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
- package/.bkit/core/engine/commands/land.ts +2 -3
- package/.bkit/core/engine/commands/lib.ts +394 -39
- package/.bkit/core/engine/commands/registry.ts +1 -1
- package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
- package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
- package/.bkit/core/engine/commands/workflow/context.ts +71 -10
- package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
- package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
- package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
- package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
- package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
- package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
- package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
- package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
- package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
- package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
- package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
- package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
- package/.bkit/core/engine/commands/workflow/status.ts +324 -11
- package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
- package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
- package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
- package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
- package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
- package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
- package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
- package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
- package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
- package/.bkit/core/engine/install/cloud-env.ts +38 -10
- package/.bkit/core/engine/install/managed-block.ts +105 -0
- package/.bkit/core/engine/install/manifest.ts +7 -1
- package/.bkit/core/engine/install/modules/claude.ts +6 -2
- package/.bkit/core/engine/install/modules/cloud.ts +84 -95
- package/.bkit/core/engine/install/modules/codex.ts +10 -2
- package/.bkit/core/engine/install/modules/core.ts +202 -26
- package/.bkit/core/engine/install/modules/opencode.ts +18 -23
- package/.bkit/core/engine/install/network-allowlist.ts +8 -3
- package/.bkit/core/engine/install/project-docs.ts +650 -0
- package/.bkit/core/engine/install/template-copies.ts +58 -5
- package/.bkit/core/engine/install/write.ts +128 -7
- package/.bkit/core/engine/ledgers/journal.ts +18 -10
- package/.bkit/core/engine/ledgers/migrate.ts +20 -8
- package/.bkit/core/engine/ledgers/status.ts +604 -8
- package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
- package/.bkit/core/engine/render/trackers.ts +46 -11
- package/.bkit/core/engine/shared/package-manager.ts +7 -3
- package/.bkit/core/engine/shared/settings.ts +12 -1
- package/.bkit/core/engine/shared/text.ts +14 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
- package/.bkit/core/engine/tools/instructions.ts +116 -20
- package/.bkit/core/hooks/antigravity-hook.js +20 -4
- package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
- package/.bkit/core/hooks/gateguard-engine.js +249 -23
- package/.bkit/core/hooks/guardrails-deny.js +167 -0
- package/.bkit/core/hooks/guardrails-read.js +3 -3
- package/.bkit/core/hooks/guardrails-shell.js +1122 -167
- package/.bkit/core/hooks/guardrails-tiers.js +247 -176
- package/.bkit/core/hooks/preflight-tracker.sh +219 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
- package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
- package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
- package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
- package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
- package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
- package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
- package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
- package/.bkit/core/prompts/bkit-design-generate.md +6 -4
- package/.bkit/core/prompts/bkit-design-organise.md +4 -3
- package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
- package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
- package/.bkit/core/prompts/bkit-design-spike.md +4 -3
- package/.bkit/core/prompts/bkit-design-update.md +6 -4
- package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
- package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
- package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
- package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
- package/.bkit/core/prompts/bkit-plan-update.md +22 -8
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
- package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
- package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
- package/.bkit/core/workflows/bkit-auto.md +23 -11
- package/.bkit/core/workflows/bkit-build.md +331 -100
- package/.bkit/core/workflows/bkit-debug.md +135 -64
- package/.bkit/core/workflows/bkit-design.md +58 -32
- package/.bkit/core/workflows/bkit-plan.md +73 -45
- package/.bkit/core/workflows/bkit-ship.md +233 -167
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
- package/.bkit/shared/.bkit/.env.example +5 -0
- package/.bkit/shared/.claude/bkit-cloud.md +7 -7
- package/.bkit/shared/.claude/settings.json +5 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
- package/.bkit/shared/.cursor/hooks.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
- package/.bkit/templates/.cursor/Dockerfile +7 -7
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
- package/.bkit/templates/.github/dependabot.yml +5 -0
- package/.bkit/templates/.github/renovate.json5 +5 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
- package/.bkit/templates/.husky/pre-push +123 -6
- package/.bkit/templates/context/bkit-serena.md +1 -1
- package/.bkit/templates/context/bkit-vercel.md +103 -59
- package/.bkit/templates/docs/architecture.md +98 -0
- package/.bkit/templates/docs/capabilities.md +33 -37
- package/.bkit/templates/docs/components.md +142 -0
- package/.bkit/templates/docs/data-schema.md +87 -0
- package/.bkit/{shared → templates}/docs/deployments.md +128 -142
- package/.bkit/templates/docs/design.md +117 -0
- package/.bkit/templates/docs/noise.md +54 -0
- package/.bkit/templates/docs/observability.md +99 -0
- package/.bkit/templates/docs/security.md +137 -0
- package/.bkit/templates/docs/setup.md +93 -0
- package/.bkit/templates/docs/technology.md +70 -0
- package/.bkit/{shared → templates}/docs/testing.md +200 -87
- package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
- package/.bkit/templates/slop-scan.config.json +2 -0
- package/CHANGELOG.md +79 -0
- package/DETAILS.md +661 -0
- package/README.md +73 -604
- package/dist/checks/after/auth.js +114 -46
- package/dist/checks/after/github.js +138 -35
- package/dist/checks/after/index.js +16 -4
- package/dist/checks/after/tools.js +224 -1
- package/dist/checks/before/files.js +59 -1
- package/dist/checks/before/index.js +7 -1
- package/dist/checks/status-holes.js +20 -21
- package/dist/checks/tips/catalogue.js +99 -10
- package/dist/checks/tips/detect.js +35 -3
- package/dist/checks/tips/index.js +1 -1
- package/dist/cli.js +13 -13
- package/dist/commands/ci/ci.js +113 -20
- package/dist/commands/ci/push-gate.js +79 -44
- package/dist/commands/install/doctor.js +5 -5
- package/dist/commands/install/install.js +23 -22
- package/dist/commands/install/uninstall.js +36 -30
- package/dist/commands/install/upgrade.js +10 -2
- package/dist/commands/land.js +2 -3
- package/dist/commands/lib.js +323 -25
- package/dist/commands/workflow/branches.js +312 -72
- package/dist/commands/workflow/challenge.js +66 -13
- package/dist/commands/workflow/context.js +46 -10
- package/dist/commands/workflow/counters.js +231 -23
- package/dist/commands/workflow/decisions.js +221 -106
- package/dist/commands/workflow/disk.js +2 -1
- package/dist/commands/workflow/feature-base.js +60 -0
- package/dist/commands/workflow/issues.js +243 -15
- package/dist/commands/workflow/junit.js +137 -0
- package/dist/commands/workflow/ledgers.js +726 -112
- package/dist/commands/workflow/locks.js +150 -29
- package/dist/commands/workflow/loops.js +67 -0
- package/dist/commands/workflow/open-decision.js +199 -0
- package/dist/commands/workflow/plan-blocks.js +6 -0
- package/dist/commands/workflow/plans.js +1 -1
- package/dist/commands/workflow/prs.js +272 -16
- package/dist/commands/workflow/repo.js +1 -1
- package/dist/commands/workflow/run-facts.js +6 -0
- package/dist/commands/workflow/runs.js +747 -155
- package/dist/commands/workflow/runtime.js +8 -4
- package/dist/commands/workflow/status.js +259 -13
- package/dist/commands/workflow/step-table.js +41 -15
- package/dist/commands/workflow/steps.js +530 -26
- package/dist/commands/workflow/summary-findings.js +1 -1
- package/dist/commands/workflow/summary.js +289 -8
- package/dist/commands/workflow/tasks.js +294 -27
- package/dist/commands/workflow/tests-base.js +266 -0
- package/dist/commands/workflow/tests-changed.js +130 -56
- package/dist/commands/workflow/tests-jump.js +77 -0
- package/dist/commands/workflow/tests.js +608 -131
- package/dist/commands/workflow/tracker.js +920 -112
- package/dist/commands/workflow/workflows.js +80 -59
- package/dist/commands/workflow/worktrees.js +387 -58
- package/dist/install/cloud-env.js +32 -10
- package/dist/install/managed-block.js +101 -0
- package/dist/install/manifest.js +7 -1
- package/dist/install/modules/claude.js +6 -2
- package/dist/install/modules/cloud.js +73 -86
- package/dist/install/modules/codex.js +9 -2
- package/dist/install/modules/core.js +190 -27
- package/dist/install/modules/opencode.js +18 -23
- package/dist/install/network-allowlist.js +8 -3
- package/dist/install/project-docs.js +551 -0
- package/dist/install/template-copies.js +55 -5
- package/dist/install/write.js +117 -5
- package/dist/ledgers/journal.js +10 -8
- package/dist/ledgers/migrate.js +20 -9
- package/dist/ledgers/status.js +461 -8
- package/dist/ledgers/telemetry.js +71 -13
- package/dist/render/trackers.js +21 -12
- package/dist/shared/package-manager.js +7 -2
- package/dist/shared/settings.js +8 -0
- package/dist/shared/text.js +13 -0
- package/dist/tools/instructions-sources.js +1 -0
- package/dist/tools/instructions.js +97 -24
- package/package.json +23 -15
- package/.bkit/core/hooks/preflight-linear.sh +0 -73
- package/.bkit/shared/docs/architecture.md +0 -16
- package/.bkit/shared/docs/data-schema.md +0 -16
- package/.bkit/shared/docs/design.md +0 -38
- package/.bkit/shared/docs/noise.md +0 -20
- package/.bkit/shared/docs/observability.md +0 -22
- package/.bkit/shared/docs/security.md +0 -62
- package/.bkit/shared/docs/setup.md +0 -52
- package/.bkit/shared/docs/technology.md +0 -15
- /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
- /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
|
@@ -26,7 +26,7 @@ Skill selection and activation within every workflow follow `.agents/skills.md`
|
|
|
26
26
|
├── bkit-plan.md # Workflow 2/5 — 8 steps; hard stop after summary
|
|
27
27
|
├── bkit-build.md # Workflow 3/5 — 16 steps; CI takes over after PR
|
|
28
28
|
├── bkit-debug.md # Workflow 4/5 — 11 steps; normal / soak modes, `[repro]`
|
|
29
|
-
├── bkit-ship.md # Workflow 5/5 —
|
|
29
|
+
├── bkit-ship.md # Workflow 5/5 — 12 steps; merge → archive → In Review (human closes)
|
|
30
30
|
└── bkit-auto.md # Utility — phase-routed cloud dispatch (plan/build by dispatch; debug/ship by CI on a PR or post-merge `dev`)
|
|
31
31
|
```
|
|
32
32
|
|
|
@@ -40,6 +40,14 @@ Skill selection and activation within every workflow follow `.agents/skills.md`
|
|
|
40
40
|
| `/bkit-ship` | yes | yes | Squash-merged PR; plans canonical at `docs/plans/{YYYYMM}/` (no archive move — `{YYYYMM}` = creation month); worktree gone |
|
|
41
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 |
|
|
42
42
|
|
|
43
|
+
## Tracker reporting
|
|
44
|
+
|
|
45
|
+
Every phase carries its explicit repo-info session into fileless reports and workflow start. The engine binds that session to the exact run so later step reports retain the same invocation. Auto and its dispatched phase keep separate invocations. A resumed exact run keeps its original association; an unrelated run never supplies one.
|
|
46
|
+
|
|
47
|
+
Routine reports may append to an eligible engine-owned progress comment. Attention reports and terminal summaries create new comments. All tracker reporting, including preparation, MCP fallback and friction, is nonfatal: attempt the report or an applicable skip, then continue substantive work. When fallback is available, publish `commentFile` byte-for-byte as one new comment and never edit prior tracker content. See `.bkit/trackers.md` § Workflow comment delivery for ownership, reconciliation and recovery.
|
|
48
|
+
|
|
49
|
+
A published build prepares its close report before the push and includes that report in its single Create PR completion comment with explicit `--purpose=terminal`. Ordinary PR-link metadata keeps the kind-based purpose, so auto's startup and Dispatch share routine progress. A held build posts its close report directly. The published completion retains its own exact fallback file after the PR link is added.
|
|
50
|
+
|
|
43
51
|
## When to Run
|
|
44
52
|
|
|
45
53
|
Choose by the state of the work. Procedure stays in the command file and in § Per-Phase Workflows.
|
|
@@ -93,12 +101,12 @@ Rendering can be re-run: the source carries every wired variant, so a tracker sw
|
|
|
93
101
|
**Rationale for the workflow files** (kept here, not in them, per `.bkit/authoring.md` § Prompts and Workflows):
|
|
94
102
|
|
|
95
103
|
- **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.
|
|
104
|
+
- **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. A holder that keeps the lock too long is stopped by the lock script at its hold limit (§ Tests lock).
|
|
97
105
|
|
|
98
106
|
- **`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
107
|
- **`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
108
|
- **`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.
|
|
109
|
+
- **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. No `CAN_SLEEP` / `RUNTIME_SLEEPS` capability row exists, 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), records each turn with `bkit runs handoff --invocation=`, and re-runs `dispatch` with the same `--invocation`. `dispatch` refuses to start without a run's invocation, because every poll and re-trigger checkpoint is saved in that run's status log and the re-run resumes from it. The gate and `runs handoff` reach their verdict through one shared decision, so the same polls give the same verdict on either path.
|
|
102
110
|
- **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
111
|
- **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
112
|
- 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.
|
|
@@ -109,7 +117,7 @@ Rendering can be re-run: the source carries every wired variant, so a tracker sw
|
|
|
109
117
|
- **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
118
|
- **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
119
|
- **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
|
-
- **
|
|
120
|
+
- **Ship retries reuse only matching feature coverage:** gate codes 10 / 11 / 14 return to CI validation; gate code 17 and revalidation code 21 return to reconciliation and refreshed feature coverage. Fresh-base code 19 returns to reconciliation and integration. Merge refusals use `route=revalidate` when the head moved and `route=integrate` for a conflict with dev. Each gate refusal or attempted merge consumes one arrival in `ship.merge.maxAttempts`. `branches sync --feature-state` recomputes coverage before each sweep/docs reuse decision. Imported feature merges and semantic conflict resolutions invalidate coverage; bookkeeping and proven automatic dev-only merges retain it.
|
|
113
121
|
- **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
122
|
- **Design / plan close on HARD STOP:** a human must review before the next phase.
|
|
115
123
|
- **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.
|
|
@@ -130,12 +138,12 @@ Rendering can be re-run: the source carries every wired variant, so a tracker sw
|
|
|
130
138
|
- **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
139
|
- **`--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.
|
|
132
140
|
- **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.
|
|
133
|
-
- **Ship never checks out `dev`:** Step
|
|
141
|
+
- **Ship never checks out `dev`:** Step 11 `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 12 stays in the feature worktree until the close lands; the close then removes it and `cd`s to `REPO_ROOT`.
|
|
134
142
|
- **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
143
|
- **`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
144
|
- **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.
|
|
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.
|
|
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.
|
|
145
|
+
- **`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. The CI-run lookup asks `gh run list` for the runs of the test workflow (`bkit.testing.ciWorkflow`) on the PR branch at the PR head commit, and takes the newest one for ship and the newest one that finished with `failure`, `timed_out` or `startup_failure` for debug, so debug is never handed a green run or a run of another workflow. A repo with no declared test workflow lists the runs of every workflow at that commit and applies the same failed-only rule for debug. Exit 8 means no such run exists, and its message names the workflow and the commit.
|
|
146
|
+
- **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. No site makes a `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`).
|
|
139
147
|
- **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.
|
|
140
148
|
- **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.
|
|
141
149
|
- **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.
|
|
@@ -161,7 +169,7 @@ Rendering can be re-run: the source carries every wired variant, so a tracker sw
|
|
|
161
169
|
|
|
162
170
|
## Two-Layer Separation Rules
|
|
163
171
|
|
|
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.
|
|
172
|
+
> **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. Two exceptions exist, both utilities a human invokes:
|
|
165
173
|
>
|
|
166
174
|
> - `bkit-utility-update-roadmap` holds read-only grants (`list_issues`, `issue_read` / `get_issue`, `searchJiraIssuesUsingJql` / `getJiraIssue`) and never writes.
|
|
167
175
|
> - `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.
|
|
@@ -190,7 +198,7 @@ Every phase command (`design`, `plan`, `build`, `debug`, `ship`) shares this ske
|
|
|
190
198
|
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`)
|
|
191
199
|
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}`)
|
|
192
200
|
7. Phase-specific steps (subagent invocations, gates, per-step new comment post)
|
|
193
|
-
8. Summary step (`bkit workflows summary` → commit → push → verdict)
|
|
201
|
+
8. Summary step (`bkit workflows summary` → commit → push (build and debug only) → verdict)
|
|
194
202
|
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)
|
|
195
203
|
```
|
|
196
204
|
|
|
@@ -203,11 +211,12 @@ Every phase command (`design`, `plan`, `build`, `debug`, `ship`) shares this ske
|
|
|
203
211
|
**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:
|
|
204
212
|
|
|
205
213
|
- `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
|
|
214
|
+
- `build` / `ship`: 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.
|
|
215
|
+
- `debug`: setup adopts or resumes the existing branch without starting a rebase, preserving the original failed commit for CI evidence ancestry checks. It prepares the worktree's inputs and dependencies, and reports any rebase already in progress for resolution before proceeding.
|
|
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
|
|
217
|
+
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 11 `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.
|
|
209
218
|
|
|
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
|
|
219
|
+
**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 12 close commit. `cloud` is a stateless dispatcher with no `status.jsonl` (tracker comment only). See § `status.jsonl` — workflow state SoT.
|
|
211
220
|
|
|
212
221
|
### Header bullets
|
|
213
222
|
|
|
@@ -226,13 +235,13 @@ The table lists the header bullets of the 6 workflow files, block by block, in f
|
|
|
226
235
|
| **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
236
|
| **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
237
|
| **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
|
|
238
|
+
| **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, or a `DECIDED` / `ASSUMED` one no `build-decision` row names, as `openDecision`; for debug, `status resume` also prints Step 3's test round (`testVerdict`, `testSource`, `normalAttempt`). |
|
|
230
239
|
| **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
240
|
| **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 →
|
|
241
|
+
| **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 → `locks acquire` exits 8 and the run stops with no Failure Path (no label, comment or status row; tells the owner who holds the feature and since when); any other holder's lock reclaimed. |
|
|
233
242
|
| **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
243
|
| **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
|
|
244
|
+
| **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 write the `**Action needed — Foreign path:**` line (commit or revert the file, then say "continue"), recording the wait (`owner-pause`, `reason=foreign-path`) and the reply (`owner-answer`), never the **Failure Path**. |
|
|
236
245
|
| **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
246
|
| **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
247
|
| **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). |
|
|
@@ -247,8 +256,9 @@ The table lists the header bullets of the 6 workflow files, block by block, in f
|
|
|
247
256
|
<!-- prettier-ignore -->
|
|
248
257
|
| Invariant | Rule |
|
|
249
258
|
| --- | --- |
|
|
250
|
-
| **
|
|
251
|
-
| **
|
|
259
|
+
| **Re-runs follow answers** | build, debug, ship: after an owner answer or an automatic one (`ask: false`, headless), a check or test runs again only when the answer changes code (`Fix now`), asks for another round (`Try again`), or a red gate is still unsettled. Otherwise the workflow goes on. Build routes a verify or holistic pause to `continue` only when `bkit decisions skip` exits 0 on its decision file, and resumes a pause that only asks to try a red gate again by re-running that gate (`status resume` `gateRerun` / `rerunFrom`); debug's Loop Question and ship's Merge Question and Confirm Assumed Items offer no answer that re-runs a check without a change. `workflow-shape.test.ts` guards the debug and ship options. |
|
|
260
|
+
| **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_FLAG}` (`--base={startSha}` when the run has a start commit, else empty). Ship Step 5 and the ship Failure Path pass `--base=origin/dev`, so the sweep reads the PR's full merge diff. |
|
|
261
|
+
| **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}`. A taken lock prints `route` `go`; an error exit (a feature split across month buckets, exit 7) prints no `route` → **Failure Path**. Existing lock → its owning workflow's folded status.jsonl decides: `IN_PROGRESS` + last step <30min → refused with exit 8 (`workflow already running for {FID}`), `heldBy` (`workflow`, `since`, `lastStepAt`, `idleSeconds`), `route` `stop` and a `message` naming the holder → the run tells the owner `message` and stops, with no Failure Path, label, comment or status row, because the other run is healthy and keeps its lock; 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
262
|
| **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
263
|
| **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
264
|
| **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. |
|
|
@@ -288,18 +298,19 @@ Rationale: keeping per-run state on `feat/{FID}` removes the divergence between
|
|
|
288
298
|
| `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
299
|
| `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
300
|
| `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
|
|
301
|
+
| `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, used-up merge limit). Written by `bkit status row` before the turn ends. Step minutes skip it. |
|
|
292
302
|
| `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
|
-
| `
|
|
303
|
+
| `run-commits` | `{type, workflow, at, startSha, commits, pushed}` | The commits a run in place on `dev` made, copied from its shared-checkout record: `startSha` = the record's start, `commits` = the run's commit ids, `pushed` = those already landed on `origin/dev` as replayed copies. `bkit workflows handover --push` writes one for a run that stays `IN_PROGRESS`, before it lands the handover, because the handover removes the record. It also parks the same start, commits and pushed list in this clone's git dir (`bkit/shared-checkout-parked/{fid}.json`). `bkit worktrees setup` rebuilds the record of the resumed run from the first of these that has one, and drops every commit id that is not an ancestor of `HEAD`: the parked copy, unless the checkout's `status.jsonl` shows the run closed; else the newest such row after the run's `workflow-started` in that log when it shows the run open; else the row on `origin/dev` when that copy shows the run open, which is the only source that fetches. A landed handover takes the row's line back out of the checkout, so the copy on `origin/dev` is a backup. Setup removes the parked copy once the record is rebuilt. Not folded; step minutes skip it. |
|
|
304
|
+
| `test-run` | `{type, workflow, at, step, attempt?, run, verdict, exitCode, failures, scope, log, artifact?, tested?, failedTests?, failedTestsTruncated?}` | 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
305
|
| `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
306
|
| `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. |
|
|
296
307
|
| `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. |
|
|
297
|
-
| `ship-merge-ci` | `{type, workflow, at, sha, run, verdict, reason}` | Step
|
|
308
|
+
| `ship-merge-ci` | `{type, workflow, at, sha, run, verdict, reason}` | Step 12's squash-merge CI verdict, written before routing: `verdict` `PASS\|FAIL`, `reason` empty on PASS. Written only for a final verdict: no row while the squash commit has no run (exit 10) or its run is still going (exit 11). A red merge is recorded, never inferred from a missing close row. Not folded. |
|
|
298
309
|
| `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. |
|
|
299
310
|
| `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
311
|
| `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. |
|
|
301
312
|
|
|
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`).
|
|
313
|
+
`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` / `continue`), 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`).
|
|
303
314
|
|
|
304
315
|
**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).
|
|
305
316
|
|
|
@@ -326,7 +337,6 @@ Ship's own audit rows (`ship-merged-on-entry`, `ship-revalidate-dispatch`, `ship
|
|
|
326
337
|
- **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
338
|
- 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
339
|
- 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
340
|
- **If** it is `DONE`/`FAILED` → start a new run.
|
|
331
341
|
|
|
332
342
|
### Context artifact clamping
|
|
@@ -445,7 +455,7 @@ Routing values that cross blocks are re-read from `status.jsonl` with `bkit stat
|
|
|
445
455
|
| `verdict` / `failures` | active-run | the step's last DONE row; `--group` optional |
|
|
446
456
|
| `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
457
|
| `strategy` | all-runs | the step's last strategy |
|
|
448
|
-
| `nextStrategy` |
|
|
458
|
+
| `nextStrategy` / `repeatTests` | all-runs | from the `test-run` rows of the fix step's test step (`fixTestStep` in `commands/workflow/loops.ts`): the latest row's `failedTests` that also failed in earlier attempts are `repeatTests`; none → `STANDARD`, a test failing in 1 earlier attempt → `PIVOT`, in 2 or more → `FINAL` (`repeatStrategy` in `ledgers/status.ts`). A gate that did not run in the round the fix follows (a group gate runs only after a passing verify) gives `STANDARD` and no `repeatTests`: its latest row is from an older attempt or run |
|
|
449
459
|
|
|
450
460
|
`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.
|
|
451
461
|
|
|
@@ -457,7 +467,7 @@ The lock is `docs/plans/{YYYYMM}/logs/{FID}/.lock` under the main checkout (ever
|
|
|
457
467
|
- 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
468
|
- `bkit locks release --token=` (Close Workflow) and `bkit workflows fail --token=` (Failure Path) release it.
|
|
459
469
|
|
|
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`.
|
|
470
|
+
**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 with exit 8, `heldBy`, `route` `stop` and the owner's `message`; the workflow follows `route` and stops without the 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`.
|
|
461
471
|
|
|
462
472
|
### Comment Lifecycle
|
|
463
473
|
|
|
@@ -465,6 +475,8 @@ Every workflow step posts a new tracker comment. Never edit, paraphrase, summari
|
|
|
465
475
|
|
|
466
476
|
**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`.
|
|
467
477
|
|
|
478
|
+
**Run proof required.** `bkit issues comment` refuses, with and without `--post`, any call that carries no proof that a workflow or audit run is making it, and exits 2 with a message that points at plain markdown through the tracker MCP. The three proofs are a `--session-dir` folder directly under the Git-common `bkit-outbox/sessions/`, a `--file` status file holding a run, and an audit call with `--kind=audit`, `--audit-slug` and a `--body-file` in that audit's own `audit-{slug}` outbox folder. Work comments outside a workflow go as plain markdown through the tracker MCP (`.agents/rules.md` § Tracker work comments), because a `###### bkit:generated` line makes later workflows drop the comment (§ Tracker context filtering).
|
|
479
|
+
|
|
468
480
|
**Step 1 (first comment):**
|
|
469
481
|
|
|
470
482
|
```comment
|
|
@@ -508,7 +520,10 @@ Each step posts its own fenced section as a fresh comment.
|
|
|
508
520
|
| --- | --- |
|
|
509
521
|
| 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
522
|
| 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. |
|
|
523
|
+
| Failed group execution or gap remediation | The latest passing verification of the same group, after the failure; a later passing holistic verification with 0 failures also covers it, because a `Fix now` can move the fix into a new group. A group that paused for the owner can also be covered by the verify-pause row below. Separate remediation warnings and flakes remain concerns. |
|
|
524
|
+
| Failed group verification, group gate or holistic gate | A later passing holistic verification (verify) or a later passing Step 12 run (group gate, holistic gate), with 0 failures. |
|
|
525
|
+
| Failed group execution, verification or gap remediation before a verify pause | The pause's decision file answers every item, and each `Fix now` item's `Fix task:` line names a task that is ticked and covered by a passing verification in its own group after the pause. A pause whose items are all `Accept` needs no fix task. FAIL rows only: remediation warnings and the accepted items stay concerns. An unanswered item, a missing or wrong `Fix task:` line, or an unticked or unverified fix task keeps the FAIL. |
|
|
526
|
+
| Failed test-fix step (build Step 14, debug Step 7) | A later passing test run in the same run with 0 failures on the same scope as the run the fix followed. A scope that differs or is missing keeps the FAIL. The failed run stays listed under `## Tests` and `Assessment History`, and the flake behind it is not a concern. |
|
|
512
527
|
| 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
528
|
| Plan currency | Later passing verification covers every task in the plan. A passing unrelated group does not resolve it. |
|
|
514
529
|
| Deferral | The latest ledger row for that key determines whether it remains open, including a closure written by another workflow. |
|
|
@@ -615,9 +630,9 @@ Every transformation step writes one versioned file in `docs/plans/{YYYYMM}/logs
|
|
|
615
630
|
- `{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
631
|
- A resume keeps the same `{RUN}`. A run after `DONE` / `FAILED` takes the next `{RUN}`.
|
|
617
632
|
- 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.
|
|
633
|
+
- `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. An existing `{workflow}-grill-{RUN}.md` in `logs/{FID}/` is appended to the end of the input file, so a rebuilt file keeps the owner-interview record.
|
|
619
634
|
|
|
620
|
-
**Build / debug / ship:** doc-producing steps adopt the same `{workflow}-v{N}-{action}.md` naming inside `logs/{FID}/`.
|
|
635
|
+
**Build / debug / ship:** doc-producing steps adopt the same `{workflow}-v{N}-{action}.md` naming inside `logs/{FID}/`. No canonical copy exists at close, because those phases don't produce a canonical artifact in `{YYYYMM}/` (only plan and design do).
|
|
621
636
|
|
|
622
637
|
**Close-workflow copy (plan + design only):** copy the highest `v{N}` matching `logs/{FID}/{workflow}-v*.md` verbatim to `{YYYYMM}/{FID}-{workflow}.md`.
|
|
623
638
|
|
|
@@ -688,10 +703,10 @@ The engine returns `progressLine` after a successful numbered completion. The or
|
|
|
688
703
|
|
|
689
704
|
```text
|
|
690
705
|
Progress: █████░░░░░ 50% · Step 8/16 Plan Verify · Group 2 of 3
|
|
691
|
-
Progress:
|
|
706
|
+
Progress: ████████░░ 83% · Step 10/12 Merge Gate + Merge PR · Attempt 2 of 3
|
|
692
707
|
```
|
|
693
708
|
|
|
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
|
|
709
|
+
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
710
|
|
|
696
711
|
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
712
|
|
|
@@ -755,7 +770,7 @@ Verdict-bearing agents with a meaningful "addressable" middle state use the 3-wa
|
|
|
755
770
|
| Agent | `Verdict` values | Routing |
|
|
756
771
|
| --- | --- | --- |
|
|
757
772
|
| `@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. |
|
|
773
|
+
| `@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. Holistic (Step 10): PASS, or CONCERNS with 0 failures, with no red holistic gate → Step 11; a red holistic gate → a fix round; other CONCERNS / FAIL → the same loop through `@bkit-build-plan-gaps-remediate` in holistic mode, counted against the run-wide `build.holistic` allowance, with no reset after a clean check. |
|
|
759
774
|
| `@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
775
|
| `@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
776
|
| `@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. |
|
|
@@ -775,7 +790,7 @@ Verdict-bearing agents with a meaningful "addressable" middle state use the 3-wa
|
|
|
775
790
|
| --- | --- | --- |
|
|
776
791
|
| Ask point limits | 2 each; grill 6 turns | `package.json` `bkit.workflows.<workflow>.<point>` (§ Ask points); read by `bkit counters max` / `route --point=` |
|
|
777
792
|
| 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 |
|
|
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`) |
|
|
793
|
+
| Lock idle threshold | 1800s | Concurrent-run cut-off: holder `IN_PROGRESS` with last-step age <30min → refused (exit 8), the run stops without the Failure Path; any other holder reclaimed at once (`WORKFLOW_LOCK_IDLE_S`, `commands/workflow/locks.ts`) |
|
|
779
794
|
| 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 |
|
|
780
795
|
| Ship CI wait | 1800s / 30s | Step 9 completion poll budget / interval (`SHIP_CI_WAIT_TIMEOUT_S` / `SHIP_POLL_INTERVAL_S`) |
|
|
781
796
|
| Ship presence probe | 6 x 10s | Step 9 run-at-head probe before any dispatch (`SHIP_PROBE_ATTEMPTS` x `SHIP_PROBE_INTERVAL_S`) |
|
|
@@ -789,7 +804,7 @@ Every command has a `🤖 Failure Path` section before Step 1. Any step, tool or
|
|
|
789
804
|
|
|
790
805
|
**Standard failure (always):**
|
|
791
806
|
|
|
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.
|
|
807
|
+
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=] [--next-step=]` (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 6 = a refused `--next-step`: not one `/bkit-*` command line (a `/bkit-` command name, then optional single-space-separated arguments of letters, digits, `#`, `.`, `_` and `-`), or still holding an unsubstituted `{UPPER}` placeholder (refused before any write, no other usage error uses it). 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
808
|
2. `--post` posts `comment` and writes the labels and state (`tracker`, `labelsWrite`). If either prints `done` = false, the tracker MCP does that write.
|
|
794
809
|
|
|
795
810
|
**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:
|
|
@@ -852,15 +867,15 @@ Step 10's `bkit prs merge --label=…` appends ` bkit [auto route]` to the squas
|
|
|
852
867
|
- `/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
868
|
- `/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.
|
|
854
869
|
|
|
855
|
-
**Why re-read must precede commit:** the
|
|
870
|
+
**Why re-read must precede commit:** the label 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.
|
|
856
871
|
|
|
857
872
|
**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.
|
|
858
873
|
|
|
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.
|
|
874
|
+
**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. The PR title is not edited (unlike `bkit [verbose ci]` in debug PR mode), because auto-route fires on the commit message.
|
|
860
875
|
|
|
861
876
|
### `bkit [verbose ci]` Marker Propagation
|
|
862
877
|
|
|
863
|
-
`bkit [verbose ci]` is the CI commit-message / PR-title marker (
|
|
878
|
+
`bkit [verbose ci]` is the CI commit-message / PR-title marker (§ Test and release mechanics → 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".
|
|
864
879
|
|
|
865
880
|
**Why debug always-verbose, build never:**
|
|
866
881
|
|
|
@@ -899,7 +914,7 @@ Each subsection documents a command's behaviour: steps, subagents, artifacts, ve
|
|
|
899
914
|
<!-- prettier-ignore -->
|
|
900
915
|
| Step | Subagent(s) | Read | Write | Notes |
|
|
901
916
|
| --- | --- | --- | --- | --- |
|
|
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 →
|
|
917
|
+
| 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 → a `Q1 — Issue` question (one option per candidate, no recommendation), re-run on the owner's pick; 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 → an `Action needed` line), 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
918
|
| 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
919
|
| 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
920
|
| 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. |
|
|
@@ -908,9 +923,9 @@ Each subsection documents a command's behaviour: steps, subagents, artifacts, ve
|
|
|
908
923
|
| 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
924
|
| 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
925
|
| 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]
|
|
926
|
+
| 10 — Summary | `bkit workflows summary` | `status.jsonl` + `design-v3-organised.md` | `design-summary.md` | Commit `chore({FID}): summary bkit [skip ci]`, no push. `SUMMARY_VERDICT` = FAIL → Failure Path. A spike FAIL answered by apply-review is a CONCERNS reason. |
|
|
912
927
|
| 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.
|
|
928
|
+
| 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. The open questions come from `## Open Questions` in `logs/{FID}/design-summary.md`. Owner answers to them 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. |
|
|
914
929
|
|
|
915
930
|
**Hard stop in Step 12 caution block:** "Design requires human review. Do not invoke `/bkit-plan`."
|
|
916
931
|
|
|
@@ -927,12 +942,12 @@ Each subsection documents a command's behaviour: steps, subagents, artifacts, ve
|
|
|
927
942
|
| --- | --- | --- |
|
|
928
943
|
| 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
944
|
| 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. |
|
|
945
|
+
| 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 --ledger-rows` → `plan-generate-check.md`: formatting-only findings go through review and plan-update as described above; other exit 1 findings (a `ledger` finding is a `**Ledger rows:**` key with no row, or no filled line) get one targeted generator correction with the same invocation id, then the check repeats; a second exit 1 → Failure Path. The invocation id is issued with `--agent=bkit-plan-generate`, so the generator's decision and deferral rows carry it as their writer. |
|
|
931
946
|
| 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. |
|
|
932
947
|
| 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
|
|
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]
|
|
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.
|
|
948
|
+
| 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 --ledger-rows` → `plan-update-check.md` (its `--ledger-rows` check is the last ledger-row gate on the final plan), 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. |
|
|
949
|
+
| 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]`, no push. |
|
|
950
|
+
| 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. The open questions come from `## Open Questions` in `logs/{FID}/plan-summary.md`. Owner answers to them 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. |
|
|
936
951
|
|
|
937
952
|
**Hard stop in Step 8 final return:** "**HARD STOP** — do not invoke `/bkit-build`."
|
|
938
953
|
|
|
@@ -953,38 +968,42 @@ Each subsection documents a command's behaviour: steps, subagents, artifacts, ve
|
|
|
953
968
|
| 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
969
|
| 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
970
|
| 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. `
|
|
957
|
-
| 6 — Skills | `@bkit-build-install-skills` (skip if input contains `[skills=false]`) | If new skills installed → commit `chore({FID}): install
|
|
958
|
-
| 7 — Execute
|
|
959
|
-
| 8 — Verify
|
|
960
|
-
| 9 —
|
|
961
|
-
| 10 — Holistic
|
|
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
|
|
971
|
+
| 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. The step's `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. |
|
|
972
|
+
| 6 — Install Skills | `@bkit-build-install-skills` (skip if input contains `[skills=false]`) | If new skills installed → commit `chore({FID}): install-skills`. |
|
|
973
|
+
| 7 — Plan Execute | `@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 baseline and that no `BLOCKED — TASK {N}: test` line names, 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. |
|
|
974
|
+
| 8 — Plan Verify | `@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. A pause after a red gate runs the base check first (§ Decision Pause) and carries `Gate: FAIL` in its header. 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. |
|
|
975
|
+
| 9 — Plan Gaps Remediate | `@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`). No progress after a red gate → the loop question with the base-check verdict, not a bare stop. Over `build.verify.maxAttempts` → Failure Path. |
|
|
976
|
+
| 10 — Plan Verify Holistic | `@bkit-build-plan-verify` (holistic mode), then `@bkit-build-plan-gaps-remediate` (holistic mode) on gaps | After the last group, and again each time later groups ran (challenge fix groups coming back through the loop): every group of the plan plus cross-group integration, cross-checked against every group's execute log; the agent runs no tests: the holistic gate (`build-holistic-gate`, `bkit:gate:static-unit` on the files changed since its newest passing run or its fix run, from the feature base when there is none) runs on every round and a red gate always goes to a fix round whose Context names the `Holistic gate` command; run-and-attempt-numbered `build-plan-verify-holistic-{RUN}-{HOLISTIC_ATTEMPT}.md` (`counters derive --step=build-plan-verify-holistic --position=next`). Each integration gap is an `INTEGRATION:` line of the `Identified Gaps Log`, ending `— Fixable: true` unless closing it needs a choice the plan does not make. 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. PASS, or CONCERNS with 0 failures (a group-count concern), with no red holistic gate → Step 11. Else the run's holistic fix rounds (`counters route --of=build-plan-gaps-remediate-holistic:next --point=build.holistic`, one allowance per run with no reset after a clean check) decide, as at Step 8: used up → § Decision Pause with the loop question (`--loop=holistic`) when `ask` is true in a session, else Failure Path; `Fixable` = `false`, or the last round → § Decision Pause (`VERIFY_GAPS`, `From: holistic`); else a fix round in the same step: `@bkit-build-plan-gaps-remediate` with Context `Mode: Holistic` and `Scope: fixable only` reads the holistic report and the plan task blocks its gaps name, and writes `build-plan-gaps-remediate-holistic-{RUN}-{HOLISTIC_ATTEMPT}-log.md` (row `build-plan-gaps-remediate-holistic`, `--attempt-of=build-plan-verify-holistic:current`, strategy from `status route --step=build-plan-gaps-remediate-holistic`). No progress (`branches scan-diff --base=HEAD~1 --code` exit 1, or `Fixed` = 0) → § Decision Pause; else Step 10 runs again. Resume: a holistic verify row or a holistic gate row, whatever its verdict, resumes at Step 10 and the round runs again, so no run reaches Step 11 without its gate; a done holistic fix row resumes at Step 7, which runs a takeover group the fix added and goes straight on to Step 10, which judges the fix, when no group is open; a `retry` decision from holistic resumes at the fix round, which reads `HOLISTIC_ATTEMPT` back (`--position=current`). |
|
|
977
|
+
| 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 the diff from the feature's start commit, 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
978
|
| 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
|
|
965
|
-
| 14 — Remediate
|
|
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` / `
|
|
979
|
+
| 13 — Failure Diagnose | `@bkit-debug-failure-diagnose` (only if Step 12 FAIL) | Gets `Strategy` and, when any test failed in an earlier round too, `Repeat tests` (`status route` `nextStrategy` / `repeatTests`), as Steps 9 and 10's fix rounds do. 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`). |
|
|
980
|
+
| 14 — Failure Remediate | `@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`). |
|
|
981
|
+
| 15 — Summary | `bkit workflows summary` | A holistic or verify FAIL settled by an all-Accept Decision Pause (`route` = `continue`) is a Resolved Finding, with no re-run row. 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. A group's verify FAIL is resolved by a later passing holistic verify, and a group-gate or holistic-gate FAIL by a later passing Step 12 run, because a Decision Pause `Fix now` can move the fix into a new group so the failed group is never checked again. 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). |
|
|
982
|
+
| 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` / `base` / `head` and the content of the printed `bodyFile` as `body`. `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`). After the push, the labels are re-read once more; an absent `bkit:auto` stops nothing and only adds a `Label bkit:auto removed during this run` line to the final message. 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
983
|
|
|
969
|
-
**Failure Path includes handover:** when exhausted retry counts trigger it, it invokes `@bkit-debug-abort-handover` and posts the `Workflow Handover` comment.
|
|
984
|
+
**Failure Path includes handover:** when exhausted retry counts trigger it, it invokes `@bkit-debug-abort-handover` and posts the `Workflow Handover` comment. `workflows handover` prints `route` (`stop`) and `message` on every exit but 80 (the open-PR lookup needs the MCP) and an engine error, which print nothing; the workflow adds `message` to the final message and follows `route`, never the exit code, and goes on as for `stop` when none is printed. A push that reached nothing (exit 9, 10 or 11) prints the `Record not pushed` line as `message`.
|
|
970
985
|
|
|
971
986
|
#### Decision Pause
|
|
972
987
|
|
|
973
988
|
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
989
|
|
|
975
|
-
- **
|
|
990
|
+
- **Base check:** at a pause after a red group gate (Step 8) or a red final run (Step 12), `bkit tests base --log= --out=` re-runs the failing tests on the base commit (a passing push-event CI run at that exact sha settles `none`; the last CI run on `dev` never settles anything) and prints a verdict `all|some|none|unknown` (`unknown` names its reason; `some` with unchecked cases names them too). `decisions compose --base-check=` words the loop question from it: `all` recommends `Stop` and tells the owner to fix `dev` first (adopt mode: also merge `dev` into the branch before resuming), `Try again` stays offered in every case. The header carries `Gate: FAIL`, and the round counts include the gate's failing tests, so a red gate never shows `0 → 0`. Gate and suite failures are never items.
|
|
991
|
+
- **Resume into a red-gate pause:** `openDecision.gate` = `FAIL`, `openDecision` `status` = `OPEN` and the loop question is the pause's only undecided question → the resume skips the question and re-runs the gate first (`decisions apply --by=rerun`, no `counters grant`); any other `Gate: FAIL` pause (a `DECIDED` / `ASSUMED` file, which keeps the owner's route, a file with no loop question, or undecided item questions) resumes at **Decision Pause** step 3. Green → the build continues without asking; still red → the pause is asked again with fresh numbers.
|
|
992
|
+
- **Resume after the answers:** a run stopped after step 6 wrote the answers (`Status: DECIDED` or `ASSUMED`) but before `steps finish --step=build-decision` has a decision file no `build-decision` row names; `openDecision` returns it, so the resume goes back to step 3 and step 5 reuses the task each `Fix task:` line names. An `Accept` or `Accept (assumed)` item that already carries a `Decision:` line writes nothing again: no second `docs/decisions.jsonl` row, no second title suffix, no second `TEST EXCEPTION`, and step 6 adds a `Decision:` line only under an item that has none. A decided file a `build-decision` row names is not reopened, and `decisions compose` is unchanged.
|
|
993
|
+
- **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|CHANGED_TESTS|UNPROVEN`), `From` (`verify` / `holistic` / `challenge` / `tests` / `summary`), `Pause step`, `Group` (verify), `Verify attempt` or `Test attempt`, `Plan`), the `{workflow} {point}: attempt {n} of {max}` line (`{n}` the rounds run, never above `{max}`: an `--attempt` above `--max` is the round the limit refused) and `## Progress` block for loop questions (`--loop`), then one item per question in the question layout (§ Ask points); a `VERIFY_GAPS` item, verify or holistic, is titled `Task {N}` when its gap names a task, so the `tasks tick --decision` tick finds it; an item answered `Fix now` also gets a `Fix task: {N}` line naming the task that carries its fix, which the summary checks. Status ends `DECIDED`, or `ASSUMED` while an assumed accept is in it.
|
|
976
994
|
- **Who asks:**
|
|
977
995
|
- **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
996
|
- **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.
|
|
997
|
+
- **Changed tests (Step 15):** before the unproven ones, `bkit tests green` over the whole plan lists each planned test a code step changed under a `BLOCKED` line (`changed`). One pause, `Question: CHANGED_TESTS`, one item per test with the step's reason and the diff of its own lines since its baseline (`changed` carries `diff` and `additive`), options `Accept` / `Stop`, recommended `Accept`; asked once per run (a decision file with `Question: CHANGED_TESTS` already there skips it). Headless → `Accept (assumed)`, which ship asks the owner to confirm. The opening skip needs both `CHANGED_TESTS` and `UNPROVEN` answers, so `tests green` still runs when only one is answered.
|
|
979
998
|
- **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.
|
|
999
|
+
- **Hard blockers:** the unfixable gaps (`no-test-first`, `test-first-malformed`, `test-first-unread`, `exception-refused`, and holistic gaps logged `Fixable: false`) and `**Fixable:** false` challenge findings. `Recommended: none — {why}`; "yes" never answers one. `Fix now` on one needs the owner's direction: with none, the pause asks what the fix should do and builds no task.
|
|
981
1000
|
- **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
1001
|
- **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
|
|
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.
|
|
1002
|
+
- **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 holistic, 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 rewrites that task in place to the owner's direction (its `DONE WHEN`, `TEST FIRST` and `Derived Test Matrix` rows, keeping its number, title, group and meta line), and a challenge-originated fix reaches the challenge reviewers again through Steps 10-11. Each `Fix now` item then gets a `Fix task: {N}` line in the decision file; an item that already has one reuses its task. Step 5 writes that line right after the task block, before `tests plan-check`, so a run stopped between the two finds it on resume. Taken without asking → `Decision: Fix now — recommended; applied without asking ({RUNTIME})`.
|
|
1003
|
+
- **Try again** (loop questions only): one more fix round on the same problems; the items wait undecided. `From: verify` → Step 9, `From: holistic` → Step 10's fix round, `From: tests` → Step 13. The round counts against the same limit. A verify or holistic pause at its used-up limit asks the loop question too (`--loop=verify`, `--loop=holistic`), in a session only.
|
|
1004
|
+
- **Allowance:** every route but Stop from a verify, holistic or tests pause runs `counters grant` for that loop (holistic counts the run's fix rounds against `build.holistic`); it writes a row only when the limit is used up and `ask` is true.
|
|
1005
|
+
- **Then:** `steps finish --step=build-decision --field=route={fix|retry|verify|holistic|tests|summary|continue} --comment-body` (decision posted to the tracker) → Step 7 (`fix`), the `tasks tick --decision` tick of the accepted gaps' tasks, made before the decision is recorded, then Step 11 (`continue` from a holistic pause, each task ticked in its own group) or Step 7 (`continue` from a verify pause), only when `bkit decisions skip` exits 0 on the decision file, Step 9 (`retry` after a verify or group-gate loop), Step 10's fix round (`retry` after a holistic loop) or Step 13 (`retry` after a tests loop), re-run Step 8 (`verify`), re-run Step 10 (`holistic`), 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 10's fix round (`build-plan-gaps-remediate-holistic`) when it was `build-plan-verify-holistic` or `build-plan-gaps-remediate-holistic`, 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.
|
|
1006
|
+
- **Fixer reads the answer:** Step 9 and Step 10's fix round (`@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. Step 7's agents read a `Fix now` direction from the task block in their brief, and Steps 8-10 read the `Decision:` lines of the decision file. No subagent learns an owner's answer 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
1007
|
- **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
1008
|
|
|
990
1009
|
#### Ask points
|
|
@@ -996,44 +1015,48 @@ Every point where a run can ask the owner has two settings under `package.json`
|
|
|
996
1015
|
| --- | --- | --- | --- |
|
|
997
1016
|
| `design.grill` | `{ "ask": true, "maxTurns": 6 }` | Interview turns, the draft acceptance turn included | Each turn's questions (§ `/bkit-design`, Grill) |
|
|
998
1017
|
| `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 |
|
|
1018
|
+
| `build.holistic` | `{ "ask": true, "maxAttempts": 2 }` | Holistic fix rounds across the run, never reset after a clean check | Loop question before a further fix round once the limit is used up; every gap item: unfixable, unchanged by a fix round, or left after the last round |
|
|
999
1019
|
| `build.challenge` | `{ "ask": true, "maxAttempts": 2 }` | Challenge rounds | Every finding item |
|
|
1000
1020
|
| `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
1021
|
| `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
1022
|
| `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: …`
|
|
1023
|
+
| `ship.merge` | `{ "ask": true, "maxAttempts": 2 }` | Failed arrivals at Step 10: gate refusals plus failed merges | `Q1 — Merge: …` when the allowance is used up on a refusal |
|
|
1004
1024
|
|
|
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.
|
|
1025
|
+
- **A used-up limit asks:** with `ask` true and not headless, a used-up `build.verify`, `build.holistic`, `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
1026
|
- **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
1027
|
- **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
1028
|
- **`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
|
|
1029
|
+
- **Question layout**, every point: the `{workflow} {point}: attempt {n} of {max}` line (loop questions; `turn` for the grill), then the shape in `.bkit/authoring.md` § Human questions. 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
1030
|
- **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
1031
|
|
|
1012
1032
|
<!-- prettier-ignore -->
|
|
1013
1033
|
| Field | Source |
|
|
1014
1034
|
| --- | --- |
|
|
1015
1035
|
| `counts` (`5 → 2`) | `failures` on each check row |
|
|
1016
|
-
| `codeChanged` | `git diff` of source (plan logs and ledgers excluded) between the
|
|
1017
|
-
| `lastStrategy` / `
|
|
1036
|
+
| `codeChanged` | `git diff` of source (plan logs and ledgers excluded) between the `parentSha` of the compared same-scope pair; `null` when git cannot compare |
|
|
1037
|
+
| `lastStrategy` / `finalSpent` | fix rows' `strategy` |
|
|
1038
|
+
| `nextStrategy` | the same label `status route` gives the fix step: from the failing tests that repeat across attempts of every run |
|
|
1039
|
+
| `gateCounts` | each round's gate failing tests (`build-group-gate-{GROUP}` for the verify loop, `build-holistic-gate` for the holistic loop), added to `counts`; a round is clean only when its gate also counted 0 |
|
|
1018
1040
|
| `minutesPerRound` | check-row timestamps |
|
|
1019
|
-
| `trend` | `worse` = count rose; `closing` = count fell and code changed
|
|
1020
|
-
| `
|
|
1041
|
+
| `trend` | Compares the earliest round with the last round's `scope` against the last round. `unknown` = a compared count is missing, or no earlier round shares the last round's `scope`; `worse` = count rose; `closing` = count fell and code changed; `stuck` = otherwise; `first-round` = one check row |
|
|
1042
|
+
| `trendLine` | One plain sentence with the compared counts and the reason for the trend; every loop question states it instead of a fixed claim |
|
|
1043
|
+
| `recommend` | `try-again` when `closing`, else `stop`; `null` on `first-round` and `unknown` |
|
|
1021
1044
|
|
|
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
|
|
1045
|
+
- **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` (`unknown` goes on to the fix without asking); `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.
|
|
1023
1046
|
|
|
1024
1047
|
### `/bkit-debug` — 11 steps
|
|
1025
1048
|
|
|
1026
1049
|
**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
1050
|
|
|
1028
|
-
**Evidence selection (Steps 1
|
|
1051
|
+
**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 ask the owner a formatted question (`**Q1 — CI run:**`; an ambiguous branch asks `**Q1 — Branch:**`) before tests or edits, and the answer is written to `{SESSION_DIR}/owner-answer.md` and parsed again. `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.
|
|
1029
1052
|
|
|
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
|
|
1053
|
+
**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. The CI evidence round's `failures` is the selected run's failed job count when `runs locate` read the jobs (capstone left out), else unknown. 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.
|
|
1031
1054
|
|
|
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
|
|
1055
|
+
**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 and exit code; its failure count is the run's failed job count when `runs locate` read the jobs, else null; 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.
|
|
1033
1056
|
|
|
1034
1057
|
**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.
|
|
1035
1058
|
|
|
1036
|
-
**Ladder + cutover:** `NORMAL` (diagnose + remediate) and `SOAK` (accumulating-context instrument-or-fix).
|
|
1059
|
+
**Ladder + cutover:** `NORMAL` (diagnose + remediate) and `SOAK` (accumulating-context instrument-or-fix). No observe mode exists; `[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.
|
|
1037
1060
|
|
|
1038
1061
|
**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
1062
|
|
|
@@ -1051,36 +1074,36 @@ The following table describes the local discovery route and shared step mechanic
|
|
|
1051
1074
|
| Step | Subagent(s) | Notes |
|
|
1052
1075
|
| --- | --- | --- |
|
|
1053
1076
|
| 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 `
|
|
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. |
|
|
1077
|
+
| 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 `START_SHA`; `{BASE_FLAG}` = `--base={startSha}` when `startSha` is present, else empty. Write the debug input and persist the attempt, modes and validated evidence selection before downstream resume. |
|
|
1078
|
+
| 3 — Run Tests | — | **Loop head (both modes).** `NORMAL_ATTEMPT` = this row's `attempt` (`steps done --attempt=next`). A resume past Step 3 holds `NORMAL_ATTEMPT`, `TEST_VERDICT` and `TEST_SOURCE` from `status resume --workflow=debug` (`normalAttempt`, `testVerdict`, `testSource`: the active run's `debug-run-tests` DONE-row count and its last row's `verdict` and `source`); exit 4 when that round cannot be read back → Failure Path. `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
1079
|
| 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
|
|
1058
|
-
| 6 — Failure Diagnose | `@bkit-debug-failure-diagnose` (only if `DEBUG_MODE` = NORMAL) | `STRATEGY` STANDARD
|
|
1080
|
+
| 5 — Failure Reproduce | `@bkit-debug-failure-reproduce` (only if `REPRO`, and the local Run Tests passed or selected CI has no reproduction for this generation yet) | 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`. Local path: `YES` → Step 3 (its FAIL row = the red; its PASS row with no fix since → Step 10); `NO` → test changes removed → Step 10. Selected CI: `YES` → Step 8 in SOAK, else Step 6; `NO` → Failure Path with the reproduction blocker. |
|
|
1081
|
+
| 6 — Failure Diagnose | `@bkit-debug-failure-diagnose` (only if `DEBUG_MODE` = NORMAL) | `STRATEGY` comes from the tests failing now: `STANDARD` when none of them failed in an earlier attempt, `PIVOT` when one earlier attempt lists a test, `FINAL` when two or more do. `Repeat tests` in its Context names the tests that failed in an earlier attempt too. 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
1082
|
| 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
1083
|
| 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
1084
|
| 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
1085
|
| 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
|
|
1086
|
+
| 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 {NOLEAK_BASE} --marker="[DEBUG-OBSERVE]" --expect-none` (`{NOLEAK_BASE}` = `--base={startSha}` in place on `dev`, else `--base=origin/dev`), exit 1 on a hit: added lines of the run's diff, 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. In PR mode the labels are re-read after the push; an absent `bkit:auto` stops nothing and only adds a `Label bkit:auto removed during this run` line to the final message. 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
1087
|
|
|
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).
|
|
1088
|
+
**Failure Path** includes a conditional handover via `@bkit-debug-abort-handover` when max-retry is exhausted → `debug-handover.md`. `workflows handover` prints `route` (`stop`) and `message` on every exit but 80 (the open-PR lookup needs the MCP) and an engine error, which print nothing; the workflow adds `message` to the final message and follows `route`, never the exit code, and goes on as for `stop` when none is printed. A push that reached nothing (exit 9, 10 or 11) prints the `Record not pushed` line as `message`. 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).
|
|
1066
1089
|
|
|
1067
|
-
### `/bkit-ship` —
|
|
1090
|
+
### `/bkit-ship` — 12 steps
|
|
1068
1091
|
|
|
1069
|
-
**Goal:** verify the PR, land docs and bookkeeping on it, merge to `dev`, and
|
|
1092
|
+
**Goal:** reconcile the local and remote feature branches, verify the resulting PR, land docs and bookkeeping on it, merge to `dev`, and remove only landed work. 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 guarded cleanup.
|
|
1070
1093
|
|
|
1071
1094
|
**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.
|
|
1072
1095
|
|
|
1073
1096
|
**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.
|
|
1074
1097
|
|
|
1075
|
-
**`ship-merged-on-entry`
|
|
1098
|
+
**`ship-merged-on-entry` requires current feature evidence.** `prs probe --ship-entry` checks local and freshly fetched remote feature work against dev before accepting a merged PR. Extra work returns the no-PR route so ship opens a new PR. Unreadable evidence refuses the shortcut. Only a branch with no remaining feature work records the marker and goes to Step 11; that route runs no docs sync and may have no summary.
|
|
1076
1099
|
|
|
1077
1100
|
**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.
|
|
1078
1101
|
|
|
1079
1102
|
**Docs and bookkeeping ride the PR (Steps 5-8):**
|
|
1080
1103
|
|
|
1081
1104
|
- 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`.
|
|
1082
|
-
- Pre-merge, every ship write has a publish channel on every runtime
|
|
1083
|
-
- Pre-merge pushes to `{SHIP_BRANCH}` happen only in these steps, none forced:
|
|
1105
|
+
- Pre-merge, every ship write has a publish channel on every runtime. The merge leaves branch deletion to guarded close, so newer feature work remains available after the PR lands.
|
|
1106
|
+
- Pre-merge pushes to `{SHIP_BRANCH}` happen only in these steps, none forced: feature reconciliation and a missing PR (Step 2), reconciliation before base classification (Step 3), integration (Step 4), Commit + Push Bookkeeping (Step 8), and regeneration (Step 10). Reconciled unpublished work has a CI-running head before the bookkeeping commit.
|
|
1084
1107
|
- 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.
|
|
1085
1108
|
|
|
1086
1109
|
**Validated-head carry-forward (Step 9 + gate `--validated`):**
|
|
@@ -1089,7 +1112,10 @@ The following table describes the local discovery route and shared step mechanic
|
|
|
1089
1112
|
- 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
1113
|
- 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
1114
|
- 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
|
|
1115
|
+
- Step 4 integrates dev locally because GitHub ignores `merge=union`. `branches sync --merge --target=origin/dev` resolves the ref before fetching and emits the pinned target for conflict continuation. After an attempted merge, `prs merge --ship-retry` independently rereads the PR: moved head returns to validation, a new conflict returns to integration, and other refusals stop with a reason. These refusals do not enter CI diagnosis or remediation.
|
|
1116
|
+
- `runs revalidate --require-reconciled` refuses newly observed feature code with exit 21 before CI validation. It records one `ship-gate-refusal` arrival and returns to Step 3 for reconciliation, inherited-dev checks and refreshed sweep/docs coverage. Bookkeeping-only descendants retain their covered head; callers without the flag retain generic revalidation.
|
|
1117
|
+
- `runs gate --fresh-base` reads fresh dev evidence and requires dev to be an ancestor of the validated code head, before accepting a CI override or bookkeeping carry-forward. Stale dev exits 19 and returns to integration within the merge allowance; missing or mismatched evidence exits 20. Scoped MCP fact files go through the same engine decisions. Their nested Actions runs must prove the requested repository, configured workflow, branch and validated head; every paginated job must prove its selected run, repository URL and head. Missing provenance refuses the gate.
|
|
1118
|
+
- The freshness check and GitHub's merge request are separate API operations. The request pins the feature head but cannot atomically pin the base. Dev may move in that interval; the post-merge squash capstone remains the detection boundary for that residual race.
|
|
1093
1119
|
- `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.
|
|
1094
1120
|
- The bookkeeping commit merges untested. `lint-staged` formats it at commit, and post-merge `dev` CI (`ship-merge-ci` row) is the backstop.
|
|
1095
1121
|
- 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.
|
|
@@ -1098,7 +1124,8 @@ The following table describes the local discovery route and shared step mechanic
|
|
|
1098
1124
|
|
|
1099
1125
|
- 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.
|
|
1100
1126
|
- 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.
|
|
1101
|
-
- The
|
|
1127
|
+
- Cleanup runs only after the close record reaches `dev`. The shared landed comparison checks file content, mode and type, and cleanup separately proves index and working-tree state. Dirty, unlanded, changed or unreadable evidence preserves the worktree/ref and reports the reason; a local ref deletion is bound to the inspected tip.
|
|
1128
|
+
- The remote feature ref is deleted only at its proved landed tip, through a lease-guarded push, and retained when origin refuses it. This does not block close-record landing or lock release. GitHub's repository-managed automatic branch deletion is a separate setting outside this guarantee.
|
|
1102
1129
|
- `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.
|
|
1103
1130
|
|
|
1104
1131
|
**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.
|
|
@@ -1107,20 +1134,18 @@ The following table describes the local discovery route and shared step mechanic
|
|
|
1107
1134
|
| Step | Subagent(s) | Notes |
|
|
1108
1135
|
| --- | --- | --- |
|
|
1109
1136
|
| 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) | — | `
|
|
1137
|
+
| 2 — Verify PR (Worktree Setup + Regression Guard) | — | Reconcile through `branches sync --reconcile-feature` before PR lookup, then plain-push the reconciled CI-running head. Setup and each reconciliation candidate refuse inherited unpublished dev commits. `prs probe --ship-entry` qualifies open/merged PRs against fresh feature evidence; no PR or extra work beyond a merged PR opens a new PR into dev. Scoped MCP facts pass through the same engine classifier. Record `ENTRY_HEAD`, then check the PR's CI. A safely qualified merged PR records `ship-merged-on-entry` and goes to Step 11. |
|
|
1111
1138
|
| 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 | — |
|
|
1113
|
-
| 4 — Integrate (Path B only) | `@bkit-ship-conflict-resolve` (exit 24 only) | `
|
|
1114
|
-
| 5 — Deferred Sweep | `@bkit-ship-deferred-sweep` |
|
|
1115
|
-
| 6 — Update Docs & Summary | `@bkit-ship-update-docs`, then `bkit workflows summary --pr={PR_NUMBER}` |
|
|
1139
|
+
| 3 — Base Check | — | Reconcile and plain-push again on every integration retry before selecting `basePath`: A → Step 5; B → Step 4. `branches sync --feature-state` computes merge-aware coverage, excluding proven automatic dev-only merges and bookkeeping. New local or imported feature work invalidates prior sweep/docs coverage. A pending feature merge passes the engine's actual target to Step 4 and returns here after resolution. |
|
|
1140
|
+
| 4 — Integrate (Path B only) | `@bkit-ship-conflict-resolve` (exit 24 only) | `branches sync --merge --target=<pinned target>` integrates dev locally, or continues the recorded feature merge. Existing mechanical settlement handles ledgers, lockfile, generated register, embedding docs and install record, then generation. Unresolved semantic paths remain in progress for the resolver, which verifies `MERGE_HEAD` equals the caller's target. Success plain-pushes, then returns to the recorded reconciliation step or Step 5. Other failures preserve/report the existing failure evidence. |
|
|
1141
|
+
| 5 — Deferred Sweep | `@bkit-ship-deferred-sweep` | Recompute feature coverage after integration, then compare the recorded successful `ship-feature-coverage` state and artifact before reuse; changed or missing state reruns the sweep. The sweep uses `branches scan-diff --disabled-tests` and `ledgers triage` for mechanical facts. PASS records the covered state; FAIL writes `.deferred-blocked` and stops before merge. Missing plans are warned and the ship input supplies intended outcomes. |
|
|
1142
|
+
| 6 — Update Docs & Summary | `@bkit-ship-update-docs`, then `bkit workflows summary --pr={PR_NUMBER}` | Recompute coverage and reuse docs work only with matching recorded feature coverage and an existing artifact; otherwise rerun the docs agent. `context ledger-scan` supplies its pending-item artifact. `roadmap feature` appends `SHIPPED` and folds the board before recording successful docs coverage. Refresh the summary on every pass; a FAIL summary stops the merge. |
|
|
1116
1143
|
| 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. |
|
|
1117
1144
|
| 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 | — |
|
|
1119
|
-
| 10 — Merge Gate + Merge PR | — | `
|
|
1120
|
-
| 11 —
|
|
1121
|
-
| 12 —
|
|
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`. |
|
|
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**. |
|
|
1145
|
+
| 9 — Re-validate | — | `runs revalidate --require-reconciled` returns newly observed feature code (21) to Step 3 within the merge allowance before resolving `VALIDATED_HEAD`. Bookkeeping retains its covered head. Wait only when `VALIDATED_HEAD` != `ENTRY_HEAD` **or** `REVALIDATE_REASON` = `gate-refusal`: probe for an existing run, dispatch only on absence, then wait at the validated head. Record `ship-revalidate-dispatch`; an exhausted CI wait records `ship-revalidate-timeout` and stops. Success → Step 10. |
|
|
1146
|
+
| 10 — Merge Gate + Merge PR | — | `runs gate --pr= --validated= --fresh-base` writes the snapshot before deciding and records each refusal once. Codes 17/19 return to Step 3; 10/11/14 return to Step 9; unavailable evidence or a title skip token stops. `prs merge --ship-retry --match-head=<gate mergeHead> --expect-merged` uses an empty body and leaves deletion to guarded close. Independent rereads return merged → Step 11, moved head (9) → validation, new conflict (10) → integration, or another explicit reason → terminal stop. The same durable allowance counts gate refusals and merge attempts. MCP fallback validates scoped pre/post facts through the engine before taking these routes. Red CI runs regenerate only when every failed step is on `CI_GENERATED_FLOOR` or `bkit.testing.ciGenerated`; committed regeneration plain-pushes and revalidates, while unchanged/undeclared/failed regeneration stops. A red CI run (here, at the Step 2 CI wait and at the Step 12 capstone) ends in the Failure Path with `Next step: /bkit-debug {FID}` in the failure comment and the final message. |
|
|
1147
|
+
| 11 — 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`. |
|
|
1148
|
+
| 12 — Close Workflow | — | `runs gate --squash-of= --capstone-only --record= --wait` reads the squash commit, waits for its CI run on the PR's base branch to finish, then records the post-merge verdict; only the squash capstone decides. A run still going when the wait runs out is exit 11, with no row. `workflows close --flush` lands the path-scoped close record through the throwaway dev checkout, or a close PR when refused. Guarded cleanup removes a clean workflow-owned worktree and landed local ref only with fresh, matching evidence; dirty/index/unlanded work and changed refs are reported and retained. The remote ref is deleted at its proved landed tip, or remains when origin refuses. Record landing and lock release continue independently of retained work. Gate 12 reads status from dev. Copy/display the summary and tips, update the issue to review, then stop. |
|
|
1124
1149
|
|
|
1125
1150
|
**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.
|
|
1126
1151
|
|
|
@@ -1141,16 +1166,191 @@ It writes only the report and the template's consumer-owned `Project Instruction
|
|
|
1141
1166
|
|
|
1142
1167
|
### `/bkit-auto` — phase-routed dispatch
|
|
1143
1168
|
|
|
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.
|
|
1169
|
+
**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. The dispatcher holds no worktree and no tracker state beyond a single comment line.
|
|
1145
1170
|
|
|
1146
1171
|
<!-- prettier-ignore -->
|
|
1147
1172
|
| Step | Notes |
|
|
1148
1173
|
| --- | --- |
|
|
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. |
|
|
1174
|
+
| 1 — Start Workflow | `bkit repo info --allow-detached` (holds `{BKIT}`, `{OUTBOX_ROOT}`, `{SESSION_DIR}`), 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
1175
|
| 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). |
|
|
1151
1176
|
|
|
1152
1177
|
**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.
|
|
1153
1178
|
|
|
1179
|
+
## Documentation Consultation Coverage
|
|
1180
|
+
|
|
1181
|
+
Every rule group, workflow step and plan-template section was reviewed for the project documents it should consult. A project document path is a recommendation: read the `.agents/docs.md` index, use the recommended path or an indexed equivalent (`Equivalent to docs/{topic}.md` in the Scope cell), and **if** the index or a document is missing, empty or still the starter, warn and continue from repository evidence. Outcomes: `added` (a named reference or section was added), `retained` (the source already cited it), `corrected` (an inappropriate or silent-skip reference was fixed) and `not-applicable` (no project document applies, with the reason). Each producing prompt writes gaps as `jsonl` records under `## Documentation Warnings`, and `bkit workflows summary` lists the current run's records once per topic and gap without changing the verdict. `.bkit/core/engine/audits/repo/shipped-docs-refs.test.ts` checks that every source has a record.
|
|
1182
|
+
|
|
1183
|
+
<!-- prettier-ignore -->
|
|
1184
|
+
| Source | Recommended documents | Outcome | Applicability and reason |
|
|
1185
|
+
| --- | --- | --- | --- |
|
|
1186
|
+
| `.bkit/core/.agents/rules.md` § New files | `docs/architecture.md` | retained | Places new files per the architecture document when present; a missing or starter-only document warns and the nearest structure applies. |
|
|
1187
|
+
| `.bkit/core/.agents/rules.md` § UI design | `docs/design.md` | retained | Applies when the change touches UI; warns and follows existing UI conventions when the document is missing. |
|
|
1188
|
+
| `.bkit/core/.agents/rules.md` § Explicit logging | `docs/observability.md` | retained | Applies to logging changes; warns and follows existing logging conventions when the document is missing. |
|
|
1189
|
+
| `.bkit/core/.agents/rules.md` § CI and deployments | `docs/deployments.md` | retained | Pushes, tags and CI behaviour point at the deployments document; the managed guides carry the bkit mechanics. |
|
|
1190
|
+
| `.bkit/core/.agents/rules.md` § Server-side validation, security and schema | `docs/security.md`, `docs/data-schema.md` | retained | Boundary notes name the security and schema documents; applicability follows the changed surface. |
|
|
1191
|
+
| `.bkit/core/.agents/rules.md` § Testing | `docs/testing.md` | retained | Tier rules and file inventory point at the testing document; `Tests discriminate` and `Test-first` stay in force without it. |
|
|
1192
|
+
| `.bkit/core/.agents/rules.md` § all other rules | n/a | not-applicable | Ledger, git, tracker, authoring and tool rules govern bkit operations and have no project-document topic. |
|
|
1193
|
+
| `.bkit/core/docs/templates/bkit-plan.md` § Pre-Flight / Dependencies | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/testing.md`, `docs/deployments.md`, `docs/design.md`, `docs/observability.md`, `docs/data-schema.md` | added | Core and Conditional items name each document, with the warn-and-continue rule. |
|
|
1194
|
+
| `.bkit/core/docs/templates/bkit-plan.md` § Documentation Consultation | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/testing.md`, `docs/data-schema.md`, `docs/design.md`, `docs/observability.md`, `docs/deployments.md` | added | New section records topic, applicability, source used, coverage, gap and action for every plan. |
|
|
1195
|
+
| `.bkit/core/docs/templates/bkit-plan.md` § Documentation Warnings | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/testing.md` | added | New section holds the structured warning records that the workflow summary aggregates. |
|
|
1196
|
+
| `.bkit/core/docs/templates/bkit-plan.md` § Data Schema Integration | `docs/data-schema.md` | retained | Reads and writes of the schema document stay explicit; absent schema documents warn through the consultation table. |
|
|
1197
|
+
| `.bkit/core/docs/templates/bkit-plan.md` § Documentation Updates | `docs/architecture.md`, `docs/technology.md`, `docs/data-schema.md`, `docs/design.md`, `docs/testing.md`, `docs/observability.md` | retained | Lists the documents a change touches; the runbook carries each as an UPDATE line. |
|
|
1198
|
+
| `.bkit/core/docs/templates/bkit-plan.md` § Agent Execution Runbook | `docs/architecture.md`, `docs/testing.md` | added | Tasks that touch an assessed topic carry READ and UPDATE lines for its document. |
|
|
1199
|
+
| `.bkit/core/docs/templates/bkit-plan.md` § Verification Plan | `docs/testing.md`, `docs/observability.md` | retained | Gate items verify tests and logging against the named documents. |
|
|
1200
|
+
| `.bkit/core/docs/templates/bkit-plan.md` § all other sections | n/a | not-applicable | Context, scenario, matrix, scope and rollback sections describe the change itself and cite no project document. |
|
|
1201
|
+
| `.bkit/core/workflows/bkit-design.md` § Step 3 Grill and Step 5 Generate Design | `docs/architecture.md`, `docs/technology.md`, `docs/security.md` | added | A design needs no plan: the generator reads the index, consults the documents and records warnings. |
|
|
1202
|
+
| `.bkit/core/workflows/bkit-design.md` § Step 10 Summary | `docs/architecture.md` | added | The summary carries Documentation Warnings from the run unchanged. |
|
|
1203
|
+
| `.bkit/core/workflows/bkit-design.md` § all other steps | n/a | not-applicable | Worktree, review, spike, organise and close steps handle files and verdicts, not project facts. |
|
|
1204
|
+
| `.bkit/core/workflows/bkit-plan.md` § Step 3 Generate Plan | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/testing.md` | added | Plan generation fills Documentation Consultation and Documentation Warnings. |
|
|
1205
|
+
| `.bkit/core/workflows/bkit-plan.md` § Step 7 Summary | `docs/testing.md` | added | Summary shows attributed warnings once per topic and gap, advisory only. |
|
|
1206
|
+
| `.bkit/core/workflows/bkit-plan.md` § all other steps | n/a | not-applicable | Start, fetch, review, apply and close steps move artifacts; reviewers consult through their prompts. |
|
|
1207
|
+
| `.bkit/core/workflows/bkit-build.md` § Step 4 Plan Convert | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/testing.md` | added | Issue-to-plan conversion carries the same consultation contract as generation. |
|
|
1208
|
+
| `.bkit/core/workflows/bkit-build.md` § Step 15 Summary | `docs/testing.md` | added | Summary carries warnings from the applicable tasks without changing the verdict. |
|
|
1209
|
+
| `.bkit/core/workflows/bkit-build.md` § all other steps | n/a | not-applicable | Group loop, tests, diagnosis and PR steps follow the plan; task prompts consult their documents. |
|
|
1210
|
+
| `.bkit/core/workflows/bkit-debug.md` § Step 5 Failure Reproduce | `docs/testing.md`, `docs/noise.md` | added | A debug run has no plan: subagents consult the testing and noise documents and warn when missing. |
|
|
1211
|
+
| `.bkit/core/workflows/bkit-debug.md` § Step 10 Summary | `docs/testing.md` | added | Summary and handover keep unresolved warnings. |
|
|
1212
|
+
| `.bkit/core/workflows/bkit-debug.md` § all other steps | n/a | not-applicable | Run-tests, context, push and close steps are mechanical and read no project document. |
|
|
1213
|
+
| `.bkit/core/workflows/bkit-ship.md` § Step 6 Update Docs and Summary | `docs/architecture.md`, `docs/deployments.md`, `docs/testing.md` | added | Documentation maintenance findings stay in the ship summary next to the edits. |
|
|
1214
|
+
| `.bkit/core/workflows/bkit-ship.md` § all other steps | n/a | not-applicable | Verify, integrate, merge and update steps handle git and CI state, not project facts. |
|
|
1215
|
+
| `.bkit/core/workflows/bkit-auto.md` § Step 2 Dispatch | n/a | not-applicable | Dispatch only routes to a phase; it forwards the phase summary and its warnings unchanged. |
|
|
1216
|
+
|
|
1217
|
+
## Test and release mechanics
|
|
1218
|
+
|
|
1219
|
+
These mechanics belong to bkit, so they live in this managed guide and do not depend on the project adopting `docs/testing.md` or `docs/deployments.md`. The project's own choices (its tiers, lanes, rollback and deploy decisions) go in those documents, copied from `.bkit/templates/docs/`. Test-first, `bkit:test:file`, `bkit:lint:file` and the JUnit failure count are described in § Local gate scripts and § Test-first above, and the wrapper script is in `.bkit/templates.md` § Local test sleep prevention.
|
|
1220
|
+
|
|
1221
|
+
### Local test sleep prevention
|
|
1222
|
+
|
|
1223
|
+
`bkit tests run`, `bkit tests changed` and the individual-file runs in `bkit tests red` / `bkit tests green` hold a macOS sleep assertion while the command runs. They use `caffeinate -is`: idle sleep is prevented on battery and AC power, and system-sleep prevention applies on AC power. The assertion ends when the command finishes or is cancelled. Other platforms run the original command.
|
|
1224
|
+
|
|
1225
|
+
For direct test commands and package scripts, adopt `scripts/ci/bkit-test-awake.mjs` as described in `.bkit/templates.md` § Local test sleep prevention. Wrap every test entry point and the complete gate chain. CI calls those same scripts. A raw runner command outside these entry points needs the wrapper too.
|
|
1226
|
+
|
|
1227
|
+
Keep the existing test timeouts. Keep the Mac's lid open; the assertion does not guarantee protection against lid closure or an explicit sleep request. The display may sleep normally.
|
|
1228
|
+
|
|
1229
|
+
### Tests lock
|
|
1230
|
+
|
|
1231
|
+
Wrap each test-running `bkit:gate:*` script with the adopted machine lock (`.bkit/templates.md` § Machine lock). The wrapped script holds the `tests` lock for the whole gate, across repositories. An unwired repository takes no lock.
|
|
1232
|
+
|
|
1233
|
+
- `bkit tests run` and `bkit tests changed` pass `--lock-wait-s` as `LOCAL_STACK_LOCK_WAIT_S`, their run name as `LOCAL_STACK_LOCK_WHO` and a fresh temp file as `LOCAL_STACK_LOCK_STATUS_FILE`; they run the declared gate without executing the lock script itself.
|
|
1234
|
+
- `bkit branches push` passes the same wait budget, its run name and its own status file to Git, and the pre-push hook inherits them. Git collapses a failing hook's exit status, so the file alone decides. A file that says the hook's gate gave up on the tests lock → exit 81 with `lockHolder`, nothing pushed, and the workflow ends the turn and re-runs the block. A file that says the lock was refused, or that the gate was stopped at the hold limit → exit 4. An empty file → a push failure.
|
|
1235
|
+
- A run that took the tests lock holds it at most `LOCAL_STACK_LOCK_HOLD_S` seconds (default 3600). At the limit the lock script stops the gate and every process started under it, frees the lock and exits 124. This is the only rule for a holder that keeps the lock too long.
|
|
1236
|
+
- The lock script's `run` writes the status file when it exits 75 (the wait gave up), 73 (the lock could not be taken) or 124 (the hold limit stopped the gate): `lock=<name>`, `outcome=gave-up`, `outcome=refused` or `outcome=held-too-long`, and `holder=<who and checkout>`. It writes `held-too-long` only when its supervisor reports the stop; a gate's own exit 124 writes no file. A nested wrapper never writes it. The outcome comes from the exit code and this file, never from the lines the script prints.
|
|
1237
|
+
- Exit 75 with `lock=tests` and `outcome=gave-up` becomes exit 81 with `lockHolder` from `holder=`. Exit 73 with `lock=tests` and `outcome=refused`, or exit 124 with `lock=tests` and `outcome=held-too-long`, becomes exit 4: the gate could not run or finish, its `test-run` row has a null verdict, never `FAIL`, and no fix round starts. A lock wait writes no `test-run` status row. Any other result is a gate failure (exit 1): exit 75, 73 or 124 with no file, an empty file or a file for another lock. A raw gate caller sees exit 75 and the printed holder line.
|
|
1238
|
+
- Light runs (`bkit tests red`, `green` and `bkit:test:file`) take no tests lock. Nested wraps reuse the live parent's tests lock. `CI=true` / `CI=1` bypasses locking.
|
|
1239
|
+
- `BKIT_TEST_SLOTS` sets the number of tests slots. The default is 2 slots on 8 or more cores for a local run, else 1; every other runtime defaults to 1 slot. A run is not local when `BKIT_RUNTIME` is set to anything but `LOCAL`; with it unset, when `.bkit/.runtime-cursor` exists in the main checkout or `CLAUDE_CODE_REMOTE` is truthy. An invalid value falls back to that default. Set it per machine, never per repo. The value is per process: set it in every place runs start from (the shell profile and each host's user-level settings) or nowhere, because runs that read different values can hold `tests` slots at once. The lock exports `BKIT_TEST_WORKERS`, which follows the chosen slot count, for the consumer to pass to its runner.
|
|
1240
|
+
- The CLI wait defaults to `BKIT_LOCK_WAIT_S`, else 60 seconds; `--lock-wait-s=0` tries once. Claude Code ships `BKIT_LOCK_WAIT_S=1200`; other hosts use the shorter wait and re-run on exit 81 (`.bkit/providers.md` § Long-running shell commands).
|
|
1241
|
+
- The script defaults to 60 seconds without a TTY when no wait is set. Waiting notes name the holders and their checkouts' earlier run times.
|
|
1242
|
+
|
|
1243
|
+
### Commit-message force tags
|
|
1244
|
+
|
|
1245
|
+
bkit's `bkit-ci.yml` recognises the tags below. They are case-sensitive and use the literal `[...]` form. A tag may appear anywhere in its source string. Tags compose: several on the same commit or PR title each fire independently.
|
|
1246
|
+
|
|
1247
|
+
**Where to put the tag:**
|
|
1248
|
+
|
|
1249
|
+
- **Direct push to `dev` or the default branch** (no PR): put the tag in the commit message (`github.event.head_commit.message`).
|
|
1250
|
+
- **Feature branch with an open PR** (open, synchronize or edit): put the tag in the PR title (`github.event.pull_request.title`). The commit message is not read, because the workflow fires on `pull_request`, not `push`.
|
|
1251
|
+
- **Both surfaces** are checked by `contains()` in the env block, and a marker in either one wins for its event. Pick the right one: `[verbose ci]` in a feature-branch commit message has no effect, because only the PR title is read.
|
|
1252
|
+
- **`workflow_dispatch`**: neither field is filled, so every marker is inert. The planner sets `MSG=""` for events other than `push` and `pull_request`, and silently drops `[force full]`, `[force build]` and `[verbose ci]`. Steer a dispatch with inputs, never a marker. Inputs are mandatory when the dispatch default is expensive, for example when a dispatch forces the metered native build lanes past their reuse gate and spends build quota on every run. Gate the lookup behind an input that defaults to `false`.
|
|
1253
|
+
|
|
1254
|
+
<!-- prettier-ignore -->
|
|
1255
|
+
| Tag | Effect | Scope |
|
|
1256
|
+
| --- | --- | --- |
|
|
1257
|
+
| `[force cache]` | Busts the task-runner cache for the run — recompute instead of replaying cache hits (e.g. turbo: `TURBO_FORCE=1`). Use when investigating suspected ghost-greens. | Read by `Detect Direct Push` |
|
|
1258
|
+
| `[force build]` | The lighter hammer. Exposes `should_force_build=true` + `run_level=full`. It does not bypass `web_affected`, so integration, e2e and @live run only when web is genuinely affected. Use it to rebuild without paying @live's side effects. Deploy steps act on it only when they gate on the output. | Read by `Detect Direct Push` |
|
|
1259
|
+
| `[force full]` | The hammer. Sets `run_level=full` and bypasses `web_affected`, so integration, `bkit-tests-e2e-web`, and `bkit-tests-live-web` run on any commit, including docs-only. The E2E spec set does not change, because a PR already runs the full suite. `@live` stays push-only: a docs-only `[force full]` push reaches it through the effective `web_affected`, but a PR or a dispatch never does. | Read by `Detect Direct Push` step |
|
|
1260
|
+
| `[verbose ci]` | Escalates log detail for one run. Shipped stub flips turbo / Node / Vercel / Supabase / Playwright knobs: `TURBO_LOG_LEVEL=full`, `NODE_OPTIONS=--trace-warnings --trace-deprecation` (a job-level `env:` key, never a `$GITHUB_ENV` write, which the runner rejects while still reporting success), `DEBUG=vercel:*,supabase:*`, plus Playwright `--trace=on` (when E2E stub enabled). Add your stack's equivalents to the same `env:`. Use when `bkit-debug` diagnose returns thin evidence; never for routine pushes (trace.zip files are MB-scale). See `docs/testing.md` for the full knob list and the `--reporter=line` hostile gap. | Read by the job-level `env:` of `bkit-tests-static` (copy the same `env:` onto each lane) |
|
|
1261
|
+
| `[skip ci]` / `[skip actions]` | Honoured natively by GitHub Actions, so it suppresses workflow dispatch entirely. Use sparingly: the suppressed run will not appear in `gh run list`, and downstream `workflow_run` triggers will not fire. | Native GitHub behaviour, not a bkit-level toggle |
|
|
1262
|
+
|
|
1263
|
+
**Two deploy-forcing markers only: `[force build]` and `[force full]`.** No granular `[force e2e]` or `[force live]` marker exists, because they would be silent no-ops gated behind `web_affected`. `[force full]` is the single gate bypass ("validate everything"): one effective `web_affected` drives integration, e2e and @live the same way.
|
|
1264
|
+
|
|
1265
|
+
- **Precedence: `[skip ci]` / `[skip actions]` vetoes any force marker.** A `[skip ci]` commit never dispatches, because GitHub suppresses it natively before `bkit-ci.yml` runs. No force marker undoes that. To validate a commit that would be skipped, drop `[skip ci]` and push with `[force full]`.
|
|
1266
|
+
- **`[force cache]` is a separate axis.** It busts task-runner replay (for example, turbo `TURBO_FORCE=1`), which is a different axis from which lanes run. It is never folded into `[force full]`. Combine `[force full] [force cache]` for "everything, fresh."
|
|
1267
|
+
- **Marker parity (deploy-forcing set).** The e2e and @live lanes resolve a per-SHA deployment, so a marker that force-runs them must also force the host build. Otherwise the lane dies at "resolve deployment URL". The host build-cancel script (for example, Vercel `ignoreCommand`) must honor every marker in the deploy-forcing set: the shipped `[force build]` and `[force full]`, plus any consumer marker that widens a deploy-backed lane. Assert this in CI (`grep -qF` over the cancel script). `[force cache]`, `[verbose ci]` and `[skip ci]` act on the test plane only, and the cancel script does not honor them.
|
|
1268
|
+
- **Match a signature, not a spelling.** A value-list marker (`[platform web ios]`) is invisible to a substring test for `[platform web]`. Match the opening token (`[platform `) on both sides. An assertion pinned to one spelling stays green while the cancel script kills the build the marker asked for.
|
|
1269
|
+
- **A widening marker is an or term, never a condition.** A marker that adds a lane the affected graph missed must only widen. Used as a condition (`contains(plan.platforms, 'web')` in a lane `if:`), it also removes: `[platform ios]` on a web-touching commit silently drops the web lane, and the run goes green. Guard the direction with a check over the workflow text, and mutation-prove it both ways. Intent alone does not hold this shape.
|
|
1270
|
+
- **Widen the job gate and the step gates together, or not at all.** A job-level `if:` alone starts the lane while every step inside it skips. The result is a green lane that ran nothing, which is the capstone's own failure mode, arriving where the capstone cannot see it. Step-level readers of a plan value can far outnumber its job-level readers, so count them before you widen a shared plan value.
|
|
1271
|
+
- **Forcing a subset** (builds without their tests): do not widen the shared value. Derive a new boolean beside it (`build_forced` next to `web_affected`), and gate only the lanes it owns. This is valid only for a lane with no step-level reader of that value. Assert that directly, with an error message that names what breaks when someone adds one.
|
|
1272
|
+
- **Invoke the marker parser unconditionally.** A substring pre-gate in front of a parser is a silent no-op. A pre-gate on the literal `[screenshots ` with a trailing space never matches a bare `[screenshots]`, so the step exits 0 with an empty plan, and the run goes green having captured nothing. Run the parser every time, and let it own every failure class (unknown value, invalid combination, arguments to a bare flag), loudly, in the planner, before any lane starts.
|
|
1273
|
+
|
|
1274
|
+
A direct push to `dev` (no merged PR ancestry) auto-busts the task-runner cache (for example, turbo `TURBO_FORCE=1`) regardless of tags. See the `bkit-debug` runbook for why the cache is busted.
|
|
1275
|
+
|
|
1276
|
+
### Autonomous phase-close prerequisites
|
|
1277
|
+
|
|
1278
|
+
The design and plan Close Workflow lands docs on `dev` in one of two ways. Every runtime first builds the close commit off `origin/dev` and pushes it straight to `dev`. When that push goes through, no repo setting is required, and no PR is created. When GitHub refuses it (branch protection or a ruleset on `dev`), the close opens a PR and squash-merges it, which adds two repo prerequisites. Neither is pre-flighted, because no admin-scope token is required. Instead, a missing prerequisite shows itself when the close's own merge fails loudly.
|
|
1279
|
+
|
|
1280
|
+
- **Branch protection on `dev` permits the autonomous merge**, because no human review is required. The PR-path merge does not wait for checks: its merge subject carries `bkit [skip ci]`, so a docs-only close dispatches no run to wait for. A rule requiring status checks to pass will block it.
|
|
1281
|
+
- **"Automatically delete head branches" is enabled** (repo Settings → General). The PR-path close deliberately does not pass `--delete-branch`, because `gh` would also delete the local branch. That fails when the branch is checked out in a worktree, and returns non-zero after a successful merge. Head-branch cleanup relies on the repo setting instead.
|
|
1282
|
+
|
|
1283
|
+
Confirm both before running phase closes from a cloud agent session.
|
|
1284
|
+
|
|
1285
|
+
### Post-merge dev CI auto-routing
|
|
1286
|
+
|
|
1287
|
+
`bkit-cloud.yml`'s `workflow_run` trigger fires when CI completes on `feat/**` and `dev`, never on `main`. The per-branch success / failure matrix lives in `.bkit/cloud.md` § Branch-aware routing. The post-merge surfaces add the following on top of it:
|
|
1288
|
+
|
|
1289
|
+
- **Trigger scope.** Dispatch jobs gate on `workflow_run.head_repository` being this repo, so a fork PR's CI completion never boots one. On `dev`, the same gate excludes `conclusion == 'success'` outright, so a green post-merge run costs zero runner minutes. The merge already happened, so that run only confirms the regression check passed.
|
|
1290
|
+
- **FID recovery on `dev`.** No open PR exists, so `{FID}` comes from the squash-merge commit scope (`feat({FID}): …`) first. The fallback is the `bkit:fid` marker in the body of the merged same-repo PR for that SHA. **If** neither resolves → it does nothing and dispatches nothing.
|
|
1291
|
+
- **Loop bound.** A `dev` CI failure dispatches `/bkit-debug` until the `{FID}` has `bkit.workflows.debug.fix.maxAttempts` + `bkit.workflows.debug.soak.maxAttempts` distinct failed CI SHAs (2 + 2 by default). `/bkit-debug` creates no branch of its own, so on this surface it remediates on `dev` itself, and its push re-triggers this same router. The cap is what ends that loop. `feat/**` is not capped here. `/bkit-debug` bounds it with the same two limits, counted across every debug run of the feature.
|
|
1292
|
+
|
|
1293
|
+
**Auto-route contract:** whenever the issue carries `bkit:auto`, `/bkit-ship` adds the `bkit [auto route]` free-tier gate marker to the squash-merge `--subject` (not just the sync-merge commit). That marker is what lets `dev`-triggered runs through the existing `bkit-cloud.yml` gate, and there is no second gate path. The `[skip ci]` ship-DONE close commit that follows the squash merge never carries the marker and never triggers CI, so it cannot interact with this trigger. The trust surface, the kill switch and the cap's tamper caveat belong in the project's security document (`docs/security.md`, when adopted).
|
|
1294
|
+
|
|
1295
|
+
**Docs-only-diff precondition:** the `dev`-trigger path routes every post-merge CI failure to `/bkit-debug`. That is correct for docs-only diffs only when the consumer's `bkit-ci.yml` deploy-await step treats a host-cancelled build as a skip, not a red (skip e2e and stay green; for example, Vercel `CANCELED`). **If** a consumer reds on a host-cancelled build → every docs-only squash-merge to `dev` falsely dispatches `/bkit-debug` and burns loop-cap budget. Verify this for each consumer before you rely on the `dev` trigger.
|
|
1296
|
+
|
|
1297
|
+
**Consumer-repo acceptance note:** the full happy-path loop (squash-merge → post-merge CI → `workflow_run` → `/bkit-debug` dispatch → fix PR → re-merge) can only be exercised on consumer repos that have `bkit-cloud.yml` installed and its dispatch secrets wired (see the cloud-agent auth surfaces in `.bkit/cloud.md`). A consumer without `bkit-cloud.yml` installed, or without CI running on `push: branches: [dev]`, never emits the `workflow_run` event this trigger depends on. The feature then becomes a silent no-op, not a failure.
|
|
1298
|
+
|
|
1299
|
+
### Ship gate + bookkeeping
|
|
1300
|
+
|
|
1301
|
+
`/bkit-ship` first reconciles the feature branch with `origin/{branch}` (`bkit branches sync --reconcile-feature`): it fast-forwards a behind branch, merges a diverged one (never a rebase or force-push) and plain-pushes unpublished code with a CI-running head. Setup and every reconciled candidate refuse inherited unpublished `dev` commits, naming them. It is then keyed on `bkit branches sync --head=<PR head>`, which reports whether `origin/dev` is an ancestor of the PR head (`basePath`). A merged PR is reused only when the branch holds no work past its recorded head; otherwise ship opens a new PR.
|
|
1302
|
+
|
|
1303
|
+
- **Path A** (`dev` has not moved) resumes read-only: no merge, no bookkeeping commits, no push. Then it merges.
|
|
1304
|
+
- **Path B** (`dev` moved) merges `origin/dev` into the feature branch locally with `bkit branches sync --merge`, pushes it plain, and re-validates the merged head. The block commits the run's uncommitted work first, unions the append-only ledgers, takes a conflicted lockfile from `dev` before regenerating it, takes a conflicted generated register (`docs/capabilities.md`) from `dev` before rebuilding it, with `dev`'s copy of the generated block in a doc the register's script copies that block into, and merges a conflicted install record (`.bkit/version`) entry by entry, with `dev`'s value where both sides changed an entry; a conflict outside those goes to `@bkit-ship-conflict-resolve`, which hand-resolves it and re-runs the block. A server-side update-branch is never used, because GitHub ignores `merge=union` and reports a ledger-only divergence as a conflict.
|
|
1305
|
+
|
|
1306
|
+
Both paths end at the same gate: `bkit runs gate --head=<current> --fresh-base` exits 0 (capstone concluded `success`) at the current PR head. `--fresh-base` also requires a freshly fetched `dev` to be an ancestor of the validated code head, before any override or bookkeeping carry-forward. Stale `dev` exits 19 and returns to the Step 4 integration; missing or mismatched base evidence exits 20. Merge refusals are classified by `bkit prs merge --ship-retry` from an independent reread: a moved head returns to validation, a new conflict with `dev` returns to integration, and any other refusal stops with its reason. All of these consume the same `bkit.workflows.ship.merge.maxAttempts` allowance. The merge API does not pin the base SHA, so a `dev` update between the final read and the merge remains a residual race; the post-merge capstone check reports it. Exit codes: `bkit runs gate --help`.
|
|
1307
|
+
|
|
1308
|
+
### Consumer CI contract — `pull_request` resolves to `run_level=full`
|
|
1309
|
+
|
|
1310
|
+
The merge gate (`bkit runs gate`) asserts the capstone job's `conclusion=success` at the head being merged. That assertion only means something while `pull_request => run_level=full` holds: the capstone is green because every expected tier ran and passed, not because the lanes were skipped (see `## Run-level decision matrix` above). A consumer that narrows CI on `pull_request` has, by doing so, opted out of the merge-gate guarantee:
|
|
1311
|
+
|
|
1312
|
+
- **`paths-ignore` / `paths` filters** that skip `pull_request` on some changes mean the capstone may not run at all. With no workflow run at the head, the gate refuses with code 10.
|
|
1313
|
+
- **A docs-only short-circuit** in the host's build-cancel (Vercel `ignoreCommand` / Netlify) that cancels the run mid-flight means the capstone may land `cancelled` (gate code 15) or never complete (code 11).
|
|
1314
|
+
- **A `[skip ci]` token** in a feature-branch commit subject when the PR opens makes GitHub suppress the `pull_request` run entirely. The PR's `statusCheckRollup` is then vacuously empty, so there is no run at the head (gate code 10).
|
|
1315
|
+
|
|
1316
|
+
`bkit runs gate` covers the common violation shapes. It reports a skipped non-capstone lane but does not refuse it, because the judgement of planned versus vacuous belongs to the capstone, which takes every lane result as an input and already asserts it per lane. The gate cannot make that judgement itself, because the jobs API reports no reason for a skip: a job skipped by a job-level `if:` never reaches a runner, so it carries an empty `steps` array.
|
|
1317
|
+
|
|
1318
|
+
**Code 16 is opt-in, and must stay that way.** It fires only for lanes named in `bkit.testing.ciRequired` (a package.json array), and the default empty list never refuses. A blanket refuse-on-any-skip can never be satisfied with the CI shape bkit ships. A lane whose `if:` is event-scoped cannot run pre-merge at any head: `bkit-tests-live-web` runs on a push to `dev` or the default branch only. A pre-merge gate that demands such a lane refuses every PR forever. Device lanes (`-ios` / `-android`) use the same rule on a pull request and a push, so do not treat them as post-merge canaries. Name a lane in `bkit.testing.ciRequired` only when your capstone does not assert it and the lane genuinely can run pre-merge. `BKIT_SHIP_GATE_OVERRIDE` remains the audited per-head escape hatch.
|
|
1319
|
+
|
|
1320
|
+
**Code 12 on generated files gets one fix round (`bkit.testing.ciGenerated`).** When CI fails at the head, the gate reads the run's jobs and prints each failed step outside the capstone as `{job}/{step}` (`failedSteps`). A job that failed, timed out or was cancelled with no failed step prints as `{job}/`, which matches no entry. `regenerable` = true when every failed step is on the list: the fixed floor `CI_GENERATED_FLOOR` (`bkit-tests-static/Check Capability Register`, `bkit-tests-static/Run bkit Check`, the two template steps a stale `bkit:generate` output fails) plus the repo's `bkit.testing.ciGenerated`. Ship Step 10 then runs `bkit branches regenerate`, commits only what `bkit:generate` changed, pushes and lets CI re-check, within `bkit.workflows.ship.merge.maxAttempts`. One failed step off the list sends the whole refusal to the Failure Path, because fixing half of it still leaves CI red.
|
|
1321
|
+
|
|
1322
|
+
- **Add** a step to `bkit.testing.ciGenerated` (a package.json array of `{job}/{step}`, the job id and the step's `name:` in your CI workflow) only when `bkit:generate` writes what that step checks. bkit's own repo lists `bkit-tests-static/Assert Dist Freshness`, because `bkit:generate` rebuilds `dist/`.
|
|
1323
|
+
- **A missing, malformed or empty list** leaves the floor alone. The key adds to the floor and cannot remove from it.
|
|
1324
|
+
- **A repo without a `bkit:generate` script** → `regenerate` reports `undeclared` and ship goes to the Failure Path.
|
|
1325
|
+
|
|
1326
|
+
Codes 10-15 still carry the guarantee that a green result is not vacuous: a run exists, at this head, completed, not cancelled, with the capstone present and green. Code 14 (green at a superseded head) requires `--branch`. The head-keyed run query is filtered server-side, so a moved head returns the same empty list as a head that never ran, and only a second branch-scoped query separates them.
|
|
1327
|
+
|
|
1328
|
+
A run that is present and degraded but not skipped (for example, a required lane ran a reduced test set because of a consumer config the gate cannot see) is a residual risk. It is named here, and not claimed as covered. The capstone is green because bkit's own `run_level` planner computed `full`, and a consumer narrowing inside a lane bkit does not own is invisible to the gate. Keep the capstone (`bkit-tests-check`) as the sole branch-protection required check, so `green == validated` survives a docs-only push. Do not add per-lane required checks, because a hollow lane then green-bars the capstone.
|
|
1329
|
+
|
|
1330
|
+
**No duplicate dispatch on an already-triggered head (ship Step 9):** a branch push fires `pull_request` at the new SHA on its own, unless its HEAD carries `[skip ci]`. Ship's Step 4 merge push carries no skip token, so it fires a run there. The scaffold keys a pull request on `pr-{number}` and a `workflow_dispatch` on `github.ref`. The two are separate groups, so a redundant dispatch is never cancelled and burns a full duplicate run. Ship probes the head whose CI the gate will check (`VALIDATED_HEAD`) with `bkit runs wait --head=<VALIDATED_HEAD> --branch=<branch> --until=present --dispatch-if-absent`, which dispatches only when no run appears. The probe is not a pass condition. The completion wait (`bkit runs wait --head=<VALIDATED_HEAD> --until=completed`) reads only runs at that exact head, so a completed run from a superseded head never answers it. Gate codes 10 / 11 / 14 re-enter that probe-and-poll only, never the deferred sweep. Codes 17 and 19 (and revalidation code 21) return to Step 3 or Step 4 instead, and imported feature code invalidates the covered sweep and docs work. `bkit.workflows.ship.merge.maxAttempts` bounds the retries, and it counts gate refusals and failed merges together.
|
|
1331
|
+
|
|
1332
|
+
**No CI run for ship's own docs commit (validated-head carry-forward):** ship's pre-merge `[skip ci]` bookkeeping commit (docs, summaries, ledgers, skill removals) runs no CI.
|
|
1333
|
+
|
|
1334
|
+
- **If** every path between the last CI-tested commit and the PR head is on the bookkeeping allow-list (`bkit ledgers only-bookkeeping`) → `bkit runs gate --validated=<sha>` checks CI at the tested commit.
|
|
1335
|
+
- **Else** → the gate refuses with code 17 and ship returns to Step 3 to reconcile the new feature code.
|
|
1336
|
+
|
|
1337
|
+
The merge still pins the exact head (`--match-head-commit`). A green PR costs zero extra runs. The bookkeeping commit merges untested, and post-merge `dev` CI (the `ship-merge-ci` row) is the backstop. **If** `dev` requires status checks (classic branch protection or a ruleset) → GitHub refuses a head with no run, so ship runs CI at the PR head.
|
|
1338
|
+
|
|
1339
|
+
### Consumer rollback path
|
|
1340
|
+
|
|
1341
|
+
To unwind a bad ship surface (the gate command, managed config, or a rewritten `bkit-ship.md`) without downgrading unrelated fixes:
|
|
1342
|
+
|
|
1343
|
+
1. **Pin the previous `@cbartens/bkit`** in `package.json`. The sliding `@v{N}` tag receives patches automatically, so a regression lands through the tag. Pin to the last known-good immutable `v{N}.x.y` or `@<sha>` (see § Sliding major-version tag). Re-install, and confirm that `bkit check` reports no drift.
|
|
1344
|
+
2. **Hold `bkit upgrade` for `.bkit/core/workflows/bkit-ship.md`** until the regression is fixed upstream. The gate (`bkit runs gate`) and ship's waits ship inside the `@cbartens/bkit` package (`dist/`), not as files in your repo, so the version pin in step 1 is what rolls them back. Other bkit upgrades are independent.
|
|
1345
|
+
3. **Audit any `BKIT_SHIP_GATE_OVERRIDE` rows** written in the meantime in `docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`. Each `type:"ship-gate-override"` row is a sanctioned escape that turned a refusal into a merge. Treat every row as a PR whose capstone was not green at the merged head, and re-verify it against the pinned-good gate (`bkit runs gate --head=<sha>`). `[bkit-runs] override honoured for head …` is the matching `docs/observability.md` grep key.
|
|
1346
|
+
4. **No per-workflow pin or revert exists.** The package pin plus the selective `bkit upgrade` hold is the recovery path. Document any incident in `docs/failures.jsonl`.
|
|
1347
|
+
|
|
1348
|
+
Ship's docs sync, summaries, `SHIPPED` roadmap row and skill removals ride the PR as one `[skip ci]` commit on the feature branch before the merge. The other pre-merge pushes are opening a missing PR, the Path B merge push, a `bkit:generate` commit (Path A, and the regenerate round after a red CI run). Status rows (`status.jsonl`) go to the feature worktree's tree on every runtime (`BOOK_ROOT` = `{WORKTREE_PATH}`), and ship never checks out `dev`. See `.bkit/workflows.md` § `status.jsonl` — workflow state SoT. The post-merge tail is one `[skip ci]` close commit, built in a throwaway checkout of `origin/dev`, that carries the book:
|
|
1349
|
+
|
|
1350
|
+
- Ship pushes it to `dev`.
|
|
1351
|
+
- **If** `dev` moved → ship rebuilds the commit and pushes again.
|
|
1352
|
+
- **If** the push is refused → ship opens a `ship-close/{FID}` PR.
|
|
1353
|
+
|
|
1154
1354
|
## Worktree Model
|
|
1155
1355
|
|
|
1156
1356
|
All phase workflows run in `.worktrees/{FID}` (gitignored), with one worktree per FID. The IDE's main checkout is never touched.
|
|
@@ -1161,14 +1361,14 @@ All phase workflows run in `.worktrees/{FID}` (gitignored), with one worktree pe
|
|
|
1161
1361
|
| Mode | When | Does |
|
|
1162
1362
|
| --- | --- | --- |
|
|
1163
1363
|
| `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}` |
|
|
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
|
|
1364
|
+
| `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. Setup writes nothing into the tree while it leaves a rebase in progress, because `git rebase --continue` refuses while a tracked file has unstaged changes and the run's `rebase-resolve-log.md` is tracked once a run commits it: the rows and setup's stopped note go to `bkit-rebase-note.md` in the worktree's git dir, and `bkit branches rebase --log-file` writes them ahead of its own lines once the rebase finishes or aborts. 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 |
|
|
1165
1365
|
| `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 |
|
|
1166
1366
|
|
|
1167
1367
|
Then, for `created` / `resumed` worktrees only:
|
|
1168
1368
|
|
|
1169
1369
|
- **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
1370
|
- **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.
|
|
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
|
|
1371
|
+
- **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` or a failed `direnv allow` → narrated, never fatal, with a warning that the pre-push hook blocks the first push until a human reads the file and runs `direnv allow .`. direnv missing → narrated; the hook then loads no `.envrc`. No git hook can do it: `core.hooksPath` (`.husky/_`) exists only after the install.
|
|
1172
1372
|
- `logDir` created; `baseRef` = the base above; `baseSha` = `git merge-base {baseRef} HEAD` (design / plan anchor).
|
|
1173
1373
|
|
|
1174
1374
|
Refused (exit 7): `dev` / `main` as the working branch (debug: `main` only), a detached HEAD, or ship unable to switch to its branch.
|
|
@@ -1191,7 +1391,7 @@ Refused (exit 7): `dev` / `main` as the working branch (debug: `main` only), a d
|
|
|
1191
1391
|
| --- | --- |
|
|
1192
1392
|
| `/bkit-design`, `/bkit-plan` | Squash feature branch to `dev`, push `dev`, `bkit worktrees remove --branch=feat/{FID}` (workflow-created worktree only; local + remote branch deleted unless another worktree holds it). |
|
|
1193
1393
|
| `/bkit-build`, `/bkit-debug` | Worktree persists for follow-up phases. |
|
|
1194
|
-
| `/bkit-ship` | Step
|
|
1394
|
+
| `/bkit-ship` | Step 12 dedicated cleanup: `bkit worktrees remove --branch={SHIP_BRANCH}` (removes uncommitted changes too, clears the marker, prunes, deletes the branch unless another worktree holds it). |
|
|
1195
1395
|
|
|
1196
1396
|
**Manual cross-IDE handoff** (user-triggered):
|
|
1197
1397
|
|
|
@@ -1225,8 +1425,8 @@ The phase label is kept through Close. The tracker state (GitHub `open`, Linear
|
|
|
1225
1425
|
<!-- prettier-ignore -->
|
|
1226
1426
|
| Label | Added by | When |
|
|
1227
1427
|
| --- | --- | --- |
|
|
1228
|
-
| `bkit:auto` | Human (via tracker UI) at issue creation | Opt-in gate for `/bkit-auto` CI-mode (ship / debug) dispatch
|
|
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
|
|
1428
|
+
| `bkit:auto` | Human (via tracker UI) at issue creation | Opt-in gate for `/bkit-auto` CI-mode (ship / debug) dispatch: the `bkit_gate` job in `bkit-cloud.yml` starts no agent when it is absent. No workflow removes it; build and debug re-read it after their push and stop nothing. |
|
|
1429
|
+
| `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 12 `bkit:merged`. |
|
|
1230
1430
|
|
|
1231
1431
|
### Tracker-specific state
|
|
1232
1432
|
|
|
@@ -1237,9 +1437,9 @@ Issue state semantics (GitHub `open`/`closed` + Projects v2; Linear / Jira `prog
|
|
|
1237
1437
|
| --- | --- |
|
|
1238
1438
|
| `issue-update-phase` | Step 1 of every phase. Sets phase label, tracker-specific "active" state. |
|
|
1239
1439
|
| `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`). |
|
|
1240
|
-
| `issue-update-merged` | `/bkit-ship` Step
|
|
1440
|
+
| `issue-update-merged` | `/bkit-ship` Step 12. 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). |
|
|
1241
1441
|
| `issue-update-failed` | Failure Path. Adds `bkit:failed` additive label. |
|
|
1242
|
-
| `issue-update-status` | Step 1 (design/plan/build/debug/ship) → "In progress"; phase Close (design/plan/build/debug) → "In review"; `/bkit-ship` Step
|
|
1442
|
+
| `issue-update-status` | Step 1 (design/plan/build/debug/ship) → "In progress"; phase Close (design/plan/build/debug) → "In review"; `/bkit-ship` Step 12 → "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). |
|
|
1243
1443
|
|
|
1244
1444
|
### Comment lifecycle
|
|
1245
1445
|
|
|
@@ -1302,7 +1502,7 @@ Precedence: `bkit [force build]` wins. bkit's own `bkit-ci.yml` reads markers fr
|
|
|
1302
1502
|
| `bkit [skip ci]` | GitHub Actions skip the workflow / `vercel-build` sets `run_level=none`. |
|
|
1303
1503
|
| `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. |
|
|
1304
1504
|
|
|
1305
|
-
**Docs-only commits:** workflows append `bkit [skip ci]` (CI suppression).
|
|
1505
|
+
**Docs-only commits:** workflows append `bkit [skip ci]` (CI suppression). No `bkit [skip build]` marker exists, 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.
|
|
1306
1506
|
|
|
1307
1507
|
<!-- prettier-ignore -->
|
|
1308
1508
|
| Workflow commit | Tags |
|
|
@@ -1312,7 +1512,7 @@ Precedence: `bkit [force build]` wins. bkit's own `bkit-ci.yml` reads markers fr
|
|
|
1312
1512
|
| `chore({FID}): summary bkit [skip ci]` (design Step 10 summary, plan Step 7 summary) | `bkit [skip ci]` |
|
|
1313
1513
|
| `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. |
|
|
1314
1514
|
| `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. |
|
|
1315
|
-
| `docs({FID}): ship DONE` (ship Step
|
|
1515
|
+
| `docs({FID}): ship DONE` (ship Step 12 close-workflow on `dev`, or its `ship-close/{FID}` PR squash subject) | `bkit [skip ci]` |
|
|
1316
1516
|
| `docs({FID}): {phase} aborted` (design / plan / build / debug Failure Path record on the feature branch) | `bkit [skip ci]` |
|
|
1317
1517
|
| `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]` |
|
|
1318
1518
|
| `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 |
|
|
@@ -1337,10 +1537,12 @@ An outcome-verification gate. After the final loud push, it confirms that the bk
|
|
|
1337
1537
|
- **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
1538
|
- **Debug Step 11 PR-mode:** close-workflow push (sub-step 2, `--require-ci`) = CI trigger; gate in sub-step 7.
|
|
1339
1539
|
- **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.
|
|
1340
|
-
- **Ship:** out of scope. Step
|
|
1540
|
+
- **Ship:** out of scope. Step 12 waits for the squash commit's CI run and reads it with one `bkit runs gate --squash-of=<PR> --capstone-only --wait`, which records `ship-merge-ci`. CI-Dispatch at ship would mask the "essential tests skipped" signal that ship backstops.
|
|
1341
1541
|
- **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".
|
|
1342
1542
|
- **Ship Gate 10 + squash `--body ""`:** merge — squash subject = dev HEAD.
|
|
1343
1543
|
|
|
1544
|
+
**Bounded correction and CI re-entry:** A bkit command rejected before any write (effects = none, correctable = true) gets at most two corrected retries per printed `scope` through `bkit ledgers append --correction-of=<rejected operation>`; the engine derives the scope and the count, so a replay spends nothing. Uncertain effects are reconciled with the original `--operation` first. A stricter command-specific route or limit wins; authorization, gate and check failures keep the Failure Path. The CI wait turn-loop records each poll turn with `bkit runs handoff --invocation=<id>`, and `bkit runs dispatch --invocation=<id>` resumes from the persisted rows: no counter is supplied, a re-trigger commit and push happen once, and rows for another repo, PR or head never count.
|
|
1545
|
+
|
|
1344
1546
|
**Gate outcomes (4-state terminal verdict):**
|
|
1345
1547
|
|
|
1346
1548
|
- `dispatched` — bkit CI check on pushed HEAD within poll budget. Proceed.
|
|
@@ -1360,7 +1562,7 @@ An outcome-verification gate. After the final loud push, it confirms that the bk
|
|
|
1360
1562
|
- `--budget-s` 60, `--interval-s` 10 (6 attempts).
|
|
1361
1563
|
- Log prefix `[bkit-runs]`.
|
|
1362
1564
|
- Self-heal cap = 1.
|
|
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".
|
|
1565
|
+
- 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". Other check names have no alias. 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`).
|
|
1364
1566
|
|
|
1365
1567
|
**`ciDispatch` NDJSON field (additive on `step-done` records — backward-compatible with the fold):**
|
|
1366
1568
|
|
|
@@ -1404,9 +1606,9 @@ Rationale: the invariant depends on context, because bkit pushes `[skip ci]` alo
|
|
|
1404
1606
|
| `/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
1607
|
| `/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
1608
|
| `/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 |
|
|
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
|
|
1609
|
+
| `/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 12 then gates the squash commit with `bkit runs gate --squash-of=<PR>` (not a CI-Dispatch Gate) |
|
|
1408
1610
|
| `/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. |
|
|
1409
|
-
| `/bkit-ship` |
|
|
1611
|
+
| `/bkit-ship` | 12 (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. |
|
|
1410
1612
|
|
|
1411
1613
|
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.
|
|
1412
1614
|
|
|
@@ -1418,12 +1620,12 @@ Without `acceptEdits` / a wildcard allow surface, every `Bash`, `Edit`, `Write`,
|
|
|
1418
1620
|
| Bucket | Patterns | Purpose |
|
|
1419
1621
|
| --- | --- | --- |
|
|
1420
1622
|
| `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). |
|
|
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( \*)
|
|
1623
|
+
| `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( \*)`, `\*bkit\*tests jump\*`, `\*cli.js tests jump\*`, `\*cli.ts tests jump\*`; `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. |
|
|
1422
1624
|
| `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. |
|
|
1423
1625
|
|
|
1424
|
-
Shell `curl` / `wget` are not on the Claude `ask` list. They run under `Bash(*)`, with `deny`, the auto-mode classifier, and
|
|
1626
|
+
Shell `curl` / `wget` are not on the Claude `ask` list. They run under `Bash(*)`, with `deny`, the auto-mode classifier, and `.claude/hooks/bkit-guardrails.cjs` (PreToolUse, matcher `Bash`) as the backstops. That hook refuses only the shell deny tier (force push, `rm -rf` on `/` / `~` / `$HOME`, `chmod -R 777 /`) and only advises on a `curl` / `wget` host. 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 keeps `curl *` / `wget *` at ask with no derived allow (a command-string glob cannot match a host safely; its `bkit-guardrails.js` plugin refuses the deny tier only). Cursor runs an allowlisted-host fetch unprompted; Cursor asks on an undeclared host and OpenCode asks on every shell fetch; Claude and Codex emit an advisory instead (Claude to avoid re-adding the prompt, Codex because it cannot prompt).
|
|
1425
1627
|
|
|
1426
|
-
**Shell-as-edit-channel.** `.agents/rules.md` requires edit / write tools for file contents so pre-edit gates see them; `sed -i` and
|
|
1628
|
+
**Shell-as-edit-channel.** `.agents/rules.md` requires edit / write tools for file contents so pre-edit gates see them; A known writer (`sed -i`, `tee`, `cp`, `prettier --write`, the full list in `providers.md` § GateGuard) and a redirect into a source file route around every one. `bkit-guardrails.cjs` on Claude, Codex, Cursor and Antigravity flags both. It never refuses a shell edit (Antigravity holds the call once to deliver the advice, and the retry runs), 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. The same shell edits also reach GateGuard (`bkit-gateguard.cjs`), which composes the per-file checklist and the general authoring reminder for each exact target, shares the once-per-file warning record with the edit tools, and gives one cannot-determine-all-targets notice when a known writer's target is not a literal path. Script runners such as `node` and `python3` stay silent. Output stays inside each host's response budget, and a target whose block does not fit stays unacknowledged. Under `BKIT_GATEGUARD=deny` the shell path stays advisory. `BKIT_GATEGUARD=off` silences GateGuard and leaves this guardrail as is. Limits, signatures and per-host delivery boundaries are in `providers.md` § GateGuard. OpenCode's `bkit-guardrails.js` plugin refuses the deny tier only and gives no shell-edit advice, so shell edits are uncovered there.
|
|
1427
1629
|
|
|
1428
1630
|
### Cloud sessions — what actually applies
|
|
1429
1631
|
|
|
@@ -1467,19 +1669,19 @@ Step 1 of every phase resolves `FID` before taking the lock (the lock path is `l
|
|
|
1467
1669
|
|
|
1468
1670
|
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.
|
|
1469
1671
|
|
|
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
|
|
1672
|
+
**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 shows an `Action needed — Issue reference` line asking the owner to name the issue as `#N`, its key or its URL, then waits for "continue"; never the Failure Path. `fids parse` logs the same hint without failing.
|
|
1471
1673
|
|
|
1472
1674
|
**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.
|
|
1473
1675
|
|
|
1474
1676
|
**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.
|
|
1475
1677
|
|
|
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
|
|
1678
|
+
**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 shows an `Action needed — Branch name` line asking the owner to rename the branch or name an issue, then waits for "continue"; never the Failure Path.
|
|
1477
1679
|
|
|
1478
1680
|
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.
|
|
1479
1681
|
|
|
1480
1682
|
### Branch eligibility
|
|
1481
1683
|
|
|
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.
|
|
1684
|
+
`/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. A Stop removes the record while the run stays `IN_PROGRESS`; the run's commit ids survive in a parked copy in this clone's git dir and in its `run-commits` status row (§ `status.jsonl` — workflow state SoT). The resume's setup rebuilds the record from the parked copy first, then from the row in the checkout's log, then from the row on `origin/dev` as the fallback, so the closing push still pushes them.
|
|
1483
1685
|
|
|
1484
1686
|
`/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`.
|
|
1485
1687
|
|
|
@@ -1521,15 +1723,17 @@ Each gate is the previous gate plus its own tier, so the name and the value desc
|
|
|
1521
1723
|
| `bkit:gate:format` | `pnpm lint-staged` | `.husky/pre-commit` |
|
|
1522
1724
|
| `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
1725
|
| `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
|
|
1726
|
+
| `bkit:gate:static-unit` | `pnpm bkit:gate:static && pnpm test` | build Step 12 and `.husky/pre-push` (no integration gate declared); `@bkit-build-plan-gaps-remediate` and `@bkit-debug-failure-remediate` (through `bkit tests changed`, when `bkit:gate:changed` is undeclared) |
|
|
1525
1727
|
| `bkit:gate:static-unit-integration` | not seeded — `pnpm bkit:gate:static-unit && pnpm test:integration` | build Step 12, debug Step 3, `.husky/pre-push` |
|
|
1526
|
-
| `bkit:gate:static-unit-integration-e2e` | not seeded —
|
|
1728
|
+
| `bkit:gate:static-unit-integration-e2e` | not seeded — the gate above plus E2E; runs every tier after a red one (Tier order, below) | debug Step 3 |
|
|
1527
1729
|
| `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
|
|
1730
|
+
| `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` and `@bkit-debug-failure-remediate` |
|
|
1529
1731
|
| `bkit:gate:install-static-unit-build` | `pnpm install --frozen-lockfile && pnpm bkit:gate:static-unit && pnpm build` | `@bkit-ship-conflict-resolve` |
|
|
1530
1732
|
|
|
1531
1733
|
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
1734
|
|
|
1735
|
+
Tier order: a gate runs its tiers one after another, never two at once. Running tiers side by side overloads a laptop and times tests out, which reads as a test failure. A push gate is an `&&` chain and stops at the first red tier. `bkit:gate:static-unit-integration-e2e`, and the live gate that chains it, never stops at the first red: it runs every tier after a red one and reports each tier's result, and its E2E tier runs the whole suite, with no stop-after-N-failures setting. One run then names every red tier and every failing E2E test. Keep parallel work inside a tier: a task runner fans out across packages, and the consumer caps the test runner's workers. A task runner that replays a cached task reports the earlier run's result, not a fresh run.
|
|
1736
|
+
|
|
1533
1737
|
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
1738
|
|
|
1535
1739
|
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).
|
|
@@ -1548,12 +1752,12 @@ Not seeded, because which files a stack generates is the stack's business. A reg
|
|
|
1548
1752
|
|
|
1549
1753
|
`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
1754
|
|
|
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
|
|
1755
|
+
- **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. A deleted file is left out.
|
|
1552
1756
|
- **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
1757
|
- **No files changed:** nothing runs, exit 0.
|
|
1554
1758
|
- **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
1759
|
|
|
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
|
|
1760
|
+
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 full-suite gates (build Step 12, debug Step 3, `.husky/pre-push`, CI) still run whole gates. `tests run --changed-since={sha}` runs `bkit:gate:changed` on the files changed since that commit (build Step 8 group gate, holistic checks) and passes them as arguments, plus the files that mention a deleted file; its vitest stages inherit `$BKIT_TEST_REPORT_DIR`, so a failure count survives.
|
|
1557
1761
|
|
|
1558
1762
|
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.
|
|
1559
1763
|
|
|
@@ -1561,7 +1765,7 @@ Agents and humans run the same scripts, so a green agent gate and a green `git p
|
|
|
1561
1765
|
|
|
1562
1766
|
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.
|
|
1563
1767
|
|
|
1564
|
-
Build Step 12 and debug each run the deepest gate the consumer declares, and record its name; the build group gate runs
|
|
1768
|
+
Build Step 12 and debug each run the deepest gate the consumer declares, and record its name; the build group gate runs only the files the group changed (§ Group gate):
|
|
1565
1769
|
|
|
1566
1770
|
<!-- prettier-ignore -->
|
|
1567
1771
|
| Workflow | Candidates, descending | Stops at |
|
|
@@ -1573,7 +1777,7 @@ Build stops at integration because its diagnose → remediate loop can only repa
|
|
|
1573
1777
|
|
|
1574
1778
|
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`.
|
|
1575
1779
|
|
|
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
|
|
1780
|
+
**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: any `*.xml` name, never one that another runner of the gate also writes, and nothing at all when the variable is unset. A `source: ci` round has no reports: its `failures` counts the selected run's failed CI jobs, the capstone left out, and the trend never compares it with a local round.
|
|
1577
1781
|
|
|
1578
1782
|
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`.
|
|
1579
1783
|
|
|
@@ -1581,11 +1785,11 @@ Build does not run the live tier (post-merge `bkit-tests-live` canary). Every `b
|
|
|
1581
1785
|
|
|
1582
1786
|
### Group gate
|
|
1583
1787
|
|
|
1584
|
-
Build Step 8 runs `bkit:gate:static-unit` (
|
|
1788
|
+
Build Step 8 runs `bkit:gate:static-unit` on the files the group changed (`tests run --changed-since={GROUP_BASE}`; the whole suite runs once, at Step 12) 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.
|
|
1585
1789
|
|
|
1586
1790
|
- **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.
|
|
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.
|
|
1791
|
+
- **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. A group gate that re-ran the whole suite would multiply its cost by the group count, so it tests only the group's own changes, 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.
|
|
1792
|
+
- **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. A red gate whose failing tests also fail on the base commit is not an ordering defect of the branch: the pause says so and recommends `Stop`, the owner fixes `dev` (adopt mode: merges `dev` into the branch) and resumes, and the resume re-runs the gate.
|
|
1589
1793
|
|
|
1590
1794
|
### Test-first
|
|
1591
1795
|
|
|
@@ -1595,15 +1799,19 @@ Every plan task block carries a `**TEST FIRST:**` field — one sub-bullet per t
|
|
|
1595
1799
|
| Moment | Who | What is checked |
|
|
1596
1800
|
| --- | --- | --- |
|
|
1597
1801
|
| 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
|
|
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. |
|
|
1802
|
+
| 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` (no case carries the planned name, and the report holds no case or only non-passing cases whose name contains the file's stem — an import of unwritten code; 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`. |
|
|
1803
|
+
| 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`, `changed` and `unproven`; `changed` lists each plan-named test (every group) a code step's `changedTests` record changed, with its reason, never a gap, and the report gets a `Changed by a code step` section when it is non-empty. |
|
|
1804
|
+
| Judgement (Step 8) | `@bkit-build-plan-verify` | `not-green` → `Fixable: true`; `Already landed` and `Unproven` sections → noted, no gap; `Changed by a code step` → noted, no gap when its added lines only add setup or expectations, else `test-loosened` (`Fixable: true` and the test on the `Loosened` line, or `Fixable: false` for a test of an earlier group or one an earlier verify logged); `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. |
|
|
1805
|
+
| Changed tests (Step 15) | orchestrator runs `bkit tests green` over the whole plan, log `build-tests-green-final.md` | `changed` non-empty → one § Decision Pause (`CHANGED_TESTS`), one `Accept` / `Stop` item per test. Asked once per run, before the Unproven pause. |
|
|
1601
1806
|
| 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
1807
|
|
|
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
|
|
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
|
|
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.
|
|
1808
|
+
- **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 when no case carries the planned name and the report holds no case, or every case is non-passing with a name containing the file's stem, the file is `red-not-loaded` (per-runner commands: `docs/testing.md` § Test first): the tests step writes no source, so an import of unwritten code is the expected shape of a red.
|
|
1809
|
+
- **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`, `build-plan-gaps-remediate-holistic`) re-hashes each planned test the plan names, of every group with a red row, and refuses the step when one differs from its baseline (the block its red recorded, or the block of a later `changedTests` record): exit 11, `tests` names each `{test, name}`, `touched` their files, nothing committed, `reask` names the agent; a test named by a ``BLOCKED — TASK {N}: test `{file}` `{name}` — {why}`` line (`Gap {N}` for the gap fixes) in the step's log is let through instead, only when it adds lines to the test's own lines and removes none (a removal or rewrite is refused even under that line; a reason already recorded for the test does not count again), and recorded in the step row's `changedTests` (its reason, its new block, the baseline `blob` stored with `hash-object -w` and the `after` blob), which becomes the test's next baseline; the orchestrator re-asks once (put that test back, keep the other edits, or log that line and the `DONE` line again), 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.
|
|
1810
|
+
- **Literal names:** a planned name must be a `<testcase name>` the repo's `bkit:test:file` writes (red and green match a case whose name equals it or ends with ` {name}`); a runner that reports one case per file means the plan names the file (per-runner commands: `docs/testing.md` § Test first). 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
1811
|
- **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.
|
|
1812
|
+
- **Taking over an earlier task's test:** a later task whose `TEST FIRST` names the same test file and name as an earlier task's takes that test over (`tests plan-check` lists it under `takeovers`, reported only; a bare test name matches a suite path on its last segment, while two suite paths match only whole). The tests brief lists it under `Planned tests taken over from earlier tasks`, and the tests step may rewrite it, old expectations included. Its red entry carries `from` (the earlier task); a takeover that passes after the rewrite is recorded `taken-over`, and `tests green` lists it under `takenOver` with its diff against the earlier task's red, never as a gap or `unproven`. The lock follows the takeover: the earlier task's baseline gives way to the later task's red.
|
|
1813
|
+
- **The tests step's own lock:** `steps finish --step=build-plan-tests` refuses a diff that changes an earlier task's recorded test no open task of the group names: exit 11, `tests` names each, nothing committed; the orchestrator re-asks the tests step once to put them back, then Failure Path. The same route covers Step 9's test-loosened restore. Only a per-test lock binds here: an earlier group's test whose baseline has no per-test block (no line carries its name, or its file was recorded `missing`) is locked by its whole file, which cannot tell this group's own new tests in that file from an edit, so the tests step's finish leaves it out.
|
|
1814
|
+
- **A takeover added mid-build:** a code step whose `BLOCKED` line names a test a ticked (`[x]`) task owns, with a change that removes or rewrites its lines, is contradicted. `steps finish` itself adds one takeover task per test (its `TEST FIRST` that test, `DEPENDS ON` the contradicting task when a `TASK N` line names one) in a new last group `Planned tests the build took over`, or in that group while its tests are unrecorded, plus a `Derived Test Matrix` row with the tier the file's name gives and a `build-takeover` status row. A chain of takeovers gives one entry, from the latest owner. The write is safe to repeat: an open takeover task naming the same file and name is reused, and only a missing row is written. The finish still exits 11, lists the test in `tests` and in `contradicts` (`{test, name, from, task, takeover}`), and its `problem` tells the agent to put the test back, since a BLOCKED line does not keep it; the workflow's plain exit-11 re-ask carries that `problem`. Step 8 and a resumed gate re-run run § Pending takeovers (`tasks takeover --pending`, which runs Step 7 sub-steps 3-6 for the group) first. A holistic fix round goes back through Step 7, which runs a takeover group it added (its code step, verify and tick) and goes straight to Step 10 when no group is open. No owner pause: the summary lists each test that changed hands under `## Tests that changed hands`, saying whether its red proved it failing (`red`), changed hands without a failing run (`taken-over`), updated a passing existing test (`updated`), or was not recorded red.
|
|
1607
1815
|
- **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
1816
|
- **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
1817
|
- **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.
|
|
@@ -1654,10 +1862,10 @@ Verify→remediate and diagnose→fix loops carry context through per-attempt lo
|
|
|
1654
1862
|
| Verifier / checker | Remediator | Max attempts | Escalation |
|
|
1655
1863
|
| --- | --- | --- | --- |
|
|
1656
1864
|
| `@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 |
|
|
1865
|
+
| `@bkit-build-plan-verify` (holistic) | `@bkit-build-plan-gaps-remediate` (holistic) | `build.holistic.maxAttempts` (2) fix rounds per run, never reset after a clean check; unfixable gaps or no progress → Decision Pause | Further rounds taken without asking; limit used up → Decision Pause with the loop question when `ask` is true in a session (a go-on answer grants one more allowance), else Failure Path |
|
|
1657
1866
|
| `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
|
|
1867
|
+
| 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` (`unknown` is fixed without asking); 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
1868
|
| 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` |
|
|
1661
1869
|
|
|
1662
1870
|
**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.
|
|
1663
1871
|
|