@cbartens/bkit 5.3.0 → 5.4.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.
Files changed (128) hide show
  1. package/.bkit/README.md +3 -2
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +8 -2
  4. package/.bkit/core/.bkit/README.md +2 -1
  5. package/.bkit/core/.bkit/cloud.md +33 -33
  6. package/.bkit/core/.bkit/comparison.md +1 -1
  7. package/.bkit/core/.bkit/install.md +6 -5
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +4 -3
  10. package/.bkit/core/.bkit/prompts.md +4 -3
  11. package/.bkit/core/.bkit/providers.md +1 -1
  12. package/.bkit/core/.bkit/templates.md +35 -5
  13. package/.bkit/core/.bkit/trackers.md +7 -8
  14. package/.bkit/core/.bkit/workflows.md +106 -86
  15. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  16. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  17. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  23. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  25. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  26. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  28. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  29. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  30. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  32. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  34. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  36. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  37. package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
  38. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  39. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  40. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  43. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  44. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  47. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  48. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  49. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  50. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  51. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -0
  52. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  53. package/.bkit/core/engine/cli.ts +22 -15
  54. package/.bkit/core/engine/commands/comply.ts +25 -16
  55. package/.bkit/core/engine/commands/install/install.ts +11 -4
  56. package/.bkit/core/engine/commands/land.ts +156 -0
  57. package/.bkit/core/engine/commands/lib.ts +10 -8
  58. package/.bkit/core/engine/commands/registry.ts +2 -0
  59. package/.bkit/core/engine/commands/tips.ts +7 -3
  60. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  61. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  62. package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
  63. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  64. package/.bkit/core/engine/commands/workflow/prs.ts +11 -2
  65. package/.bkit/core/engine/commands/workflow/roadmap.ts +48 -53
  66. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  67. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  68. package/.bkit/core/engine/commands/workflow/steps.ts +24 -15
  69. package/.bkit/core/engine/commands/workflow/workflows.ts +433 -265
  70. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  71. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  72. package/.bkit/core/engine/install/modules/core.ts +15 -0
  73. package/.bkit/core/engine/install/placeholders.ts +13 -17
  74. package/.bkit/core/engine/shared/settings.ts +8 -0
  75. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  76. package/.bkit/core/prompts/bkit-audit-generate.md +47 -4
  77. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -1
  78. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -1
  79. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
  80. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -1
  81. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -1
  82. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +3 -3
  83. package/.bkit/core/workflows/bkit-auto.md +2 -2
  84. package/.bkit/core/workflows/bkit-build.md +7 -7
  85. package/.bkit/core/workflows/bkit-debug.md +11 -11
  86. package/.bkit/core/workflows/bkit-design.md +20 -11
  87. package/.bkit/core/workflows/bkit-plan.md +23 -13
  88. package/.bkit/core/workflows/bkit-ship.md +82 -93
  89. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  90. package/.bkit/shared/.claude/settings.json +1 -0
  91. package/.bkit/shared/docs/deployments.md +29 -25
  92. package/.bkit/shared/gitignore +1 -2
  93. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  94. package/.bkit/templates/.github/workflows/bkit-ci.yml +7 -2
  95. package/.bkit/templates/.husky/pre-commit +6 -0
  96. package/.bkit/templates/.husky/pre-push +7 -0
  97. package/.bkit/templates/.lintstagedrc.json +5 -1
  98. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  99. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  100. package/CHANGELOG.md +48 -0
  101. package/README.md +97 -96
  102. package/dist/checks/status-holes.js +0 -1
  103. package/dist/checks/tips/catalogue.js +14 -0
  104. package/dist/checks/tips/index.js +44 -28
  105. package/dist/cli.js +22 -16
  106. package/dist/commands/comply.js +20 -13
  107. package/dist/commands/install/install.js +10 -4
  108. package/dist/commands/land.js +129 -0
  109. package/dist/commands/lib.js +9 -6
  110. package/dist/commands/registry.js +2 -0
  111. package/dist/commands/tips.js +7 -3
  112. package/dist/commands/workflow/branches.js +300 -243
  113. package/dist/commands/workflow/disk.js +452 -0
  114. package/dist/commands/workflow/issues.js +63 -27
  115. package/dist/commands/workflow/locks.js +35 -130
  116. package/dist/commands/workflow/prs.js +5 -2
  117. package/dist/commands/workflow/roadmap.js +49 -56
  118. package/dist/commands/workflow/runtime.js +3 -2
  119. package/dist/commands/workflow/status.js +32 -12
  120. package/dist/commands/workflow/steps.js +18 -11
  121. package/dist/commands/workflow/workflows.js +388 -247
  122. package/dist/commands/workflow/workstreams.js +3 -2
  123. package/dist/commands/workflow/worktrees.js +11 -1
  124. package/dist/install/modules/core.js +13 -0
  125. package/dist/install/placeholders.js +13 -19
  126. package/dist/shared/settings.js +5 -0
  127. package/dist/shared/timeouts.js +8 -7
  128. package/package.json +1 -1
@@ -25,7 +25,7 @@ Canonical source: `.bkit/core/workflows/`. `bkit install` regenerates `.claude/c
25
25
  ├── bkit-plan.md # Workflow 2/5 — 12 steps; hard stop after summary
26
26
  ├── bkit-build.md # Workflow 3/5 — 18 steps; CI takes over after PR
27
27
  ├── bkit-debug.md # Workflow 4/5 — 11 steps; normal / soak modes, `[repro]`
28
- ├── bkit-ship.md # Workflow 5/5 — 15 steps; merge → archive → In Review (human closes)
28
+ ├── bkit-ship.md # Workflow 5/5 — 14 steps; merge → archive → In Review (human closes)
29
29
  └── bkit-auto.md # Utility — phase-routed cloud dispatch (ship/debug by CI on a PR or post-merge `dev`; plan/build by dispatch)
30
30
  ```
31
31
 
@@ -119,8 +119,8 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
119
119
  - **`deferrals` / `failures` on `outcome` row = CUMULATIVE distinct `key` count, not lines:** same-`key` append (§ Updating a Row in `.bkit/jsonl.md`) → `wc -l` double-counts closed deferrals. Readers derive cycle from delta vs prior outcome row — `newFailuresThisRun` in `.bkit/core/engine/commands/analysis.ts`.
120
120
  - **CI-Dispatch poll:** `bkit runs dispatch` (`--budget-s` / `--interval-s`, default 60/10), shared by build's close-workflow and both debug close-workflow sites (PR-mode + LOCAL-mode). A poll outcome is `found` / `none` / `err`; a `sleep` that overruns its window is reported blocked instead of hanging. Self-heal cap 1; re-trigger suffix must match close-workflow suffix. `ciDispatch` verdict always on step-done record (additive field). No `CAN_SLEEP` / `RUNTIME_SLEEPS` capability row — sleeping is measured, not predicted. Blocked sleep → exit 81 → the orchestrator resolves the same poll in its turn loop (`bkit runs wait --pr= --once` per turn), then re-runs `dispatch` with `--poll-result` / `--attempts` / `--all-errored` / `--retriggered`.
121
121
  - **Open-PR pre-flight:** `bkit prs open` probes `--head` before creating: an open PR exits 3 (`--existing=fail`, the default) or is reused (`--existing=reuse`, design / plan PR close). A blind create on a branch with an open PR errors, retries, and lands in the Failure Path. Build Step 18 also probes (`bkit prs probe`) before its push.
122
- - **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. design / plan: `bkit branches land` writes the row on the branch the close squashes (local) or on `feat/{FID}` pre-merge (PR); STRAY allowlist admits both. build / debug: `bkit roadmap mirror` writes it on `feat/{FID}` (swept by `git add -A`), then copies the same row to `dev` under the dev lock — 4th staging shape: ship merges their PR a cycle later, board would otherwise lag one. The mirror waits up to 60s for the dev lock and is fail-open — busy lock / failed checkout, pull or push logs and continues; feat-side row already written. ship: `bkit roadmap feature --strict` (Step 6, below) exits 1 when the `SHIPPED` row does not land, failing the step.
123
- - **Dev-side mirror guards on `$WT` = `$REPO_ROOT`, not `RUNTIME_*`:** the mirror's fence holds no `RUNTIME_*` value — the runtime was detected in an earlier block and shell state does not cross blocks. `$WT` = `$REPO_ROOT` = adopt mode, where a `dev` checkout swaps the branch out from under the run; capability table moves both flags together (`worktrees` iff `devpushes`), so the local fact is a faithful proxy.
122
+ - **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. design / plan: `bkit branches land` writes the row into the close commit it builds in `.worktrees/_land-{FID}` (direct push) or on the branch pre-merge (PR); STRAY allowlist admits both. build / debug: `bkit roadmap mirror` writes it on `feat/{FID}` (swept by `git add -A`), then lands the same row on `dev` through the throwaway `.worktrees/_land-{FID}` landing (§ One landing routine for every dev write) — 4th staging shape: ship merges their PR a cycle later, board would otherwise lag one. The mirror is fail-open — a refused push, `dev` moving before every attempt, or a failed fetch or checkout logs and continues; feat-side row already written. ship: `bkit roadmap feature --strict` (Step 6, below) exits 1 when the `SHIPPED` row does not land, failing the step.
123
+ - **Dev-side mirror: every runtime, skipped only on `dev`:** the landing never checks out `dev`, so adopt mode mirrors like mint mode. Run on `dev` (debug adopting `dev`) → skip; its feat-side row is already a `dev` commit.
124
124
  - **Phase close never reads the tracker:** a close re-renders the `roadmap-status` block from the ledger and stops. It issues no `list_issues` and writes no label on any issue but its own. A workflow running on one issue may mutate only that issue; a tracker read touches every open one.
125
125
  - **Ship Step 6 fold runs after the two subagents, stages nothing itself:** same fence runs `bkit roadmap feature --root="$WT" --step=ship-update-docs` (`$WT` = `{WORKTREE_PATH}`): appends the `SHIPPED` row, 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 green it.
126
126
  - **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 — that is a human-invoked review, never a per-ship cost.
@@ -130,15 +130,20 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
130
130
  - **Design / plan close on HARD STOP** — human review required before next phase.
131
131
  - **No archive step in ship:** artifacts at canonical `docs/plans/{YYYYMM}/` from design start — nothing to move at close.
132
132
  - **Debug three attempt counters = mode-matched pairs**.
133
- - **Runtime capability table:** `bkit runtime detect` classifies the runtime (`LOCAL` / `GITHUB_ACTION` / `CLOUD_CLAUDE` / `CLOUD_CURSOR` / `UNKNOWN`) and emits `runtimeWorktrees` / `runtimeDevPushes` / `runtimeGithubCli` (the `runtime-resolved` row's keys; ship holds two as `{RUNTIME_DEVPUSHES}` / `{RUNTIME_WORKTREES}`) plus `runtimeHeadless`, derived from `runtime` and never stored on the row (`bkit runtime assert` re-derives it; design Step 3 holds it as `{RUNTIME_HEADLESS}`). Headless = `GITHUB_ACTION` only: a runner job ends when the agent ends its turn, so no reply reaches it. Every other runtime counts as attended; `BKIT_RUNTIME` overrides. `CLOUD_CURSOR` is detected via a `.bkit/.runtime-cursor` marker written by `.cursor/hooks/bkit-preflight.sh` when `is_background_agent` is true (Cursor exposes that only on stdin JSON to the hook, not as an env var). `RUNTIME_DEVPUSHES` is a conservative DEFAULT, never probed — a `git push --dry-run` sends no ref-update, so a protected branch's pre-receive hook never fires and a false-positive would strand a cloud session on a `dev` checkout. `runtimeGithubCli` is the one live probe (`gh auth status`). An explicit falsy primitive (`CI=false`, `GITHUB_ACTIONS=false`) means ABSENCE, not ambiguity — treating it as ambiguous would cost a laptop its worktree model; only a non-truthy, non-falsy value goes `UNKNOWN`.
134
- - **Local happy path is byte-identical across the three runtimes:** every runtime branch is additive. `RUNTIME_DEVPUSHES=true` (laptop, GH-Actions runner) runs the local block verbatim — local `merge --squash -X ours`, `docs({FID}): {phase} DONE bkit [skip ci]`, direct `dev` push, worktree teardown. Only `RUNTIME_DEVPUSHES != true` (claude.ai cloud, `unknown`) takes the PR-merge branch. Never replace a working local call site to serve a cloud runtime; branch around it.
135
- - **PR-mode design/plan closes MUST push before `bkit prs open`:** PR creation and `gh pr merge` act on the REMOTE, so a close commit that is only committed locally never enters the PR and never reaches `dev`. The `RUNTIME_DEVPUSHES=true` branch pushes `dev` directly and is unaffected; the `false` branch produces two local commits (`chore({FID}): close-workflow` carrying the `status.jsonl` rows and close telemetry, then `docs({FID}): {phase} roadmap update` carrying `.bkit/issues.jsonl` + `docs/roadmap.md`) and needs an explicit `bkit branches push --mode=feature` to publish them. Placed after the STRAY guard so nothing unvetted is published, and before `bkit prs open --existing=reuse`. Build/debug close pushes the feature branch already. Omitting it silently loses every design/plan close on the PR path.
136
- - **`bkit workflows close` runs in the worktree, before the squash, in both close modes:** the `workflow-done` row and the telemetry rows ride the `chore({FID}): close-workflow` commit on `feat/{FID}`, so the squash (local) or the PR (cloud) carries them to `dev`. `status.jsonl` and `.bkit/stats.jsonl` are `merge=union`, so the squash concatenates them with `dev`'s copies.
133
+ - **Runtime capability table:** `bkit runtime detect` classifies the runtime (`LOCAL` / `GITHUB_ACTION` / `CLOUD_CLAUDE` / `CLOUD_CURSOR` / `UNKNOWN`) and emits `runtimeWorktrees` / `runtimeDevPushes` / `runtimeGithubCli` (the `runtime-resolved` row's keys; ship holds `{RUNTIME_WORKTREES}`) plus `runtimeHeadless`, derived from `runtime` and never stored on the row (`bkit runtime assert` re-derives it; design Step 3 holds it as `{RUNTIME_HEADLESS}`). Headless = `GITHUB_ACTION` only: a runner job ends when the agent ends its turn, so no reply reaches it. Every other runtime counts as attended; `BKIT_RUNTIME` overrides. `CLOUD_CURSOR` is detected via a `.bkit/.runtime-cursor` marker written by `.cursor/hooks/bkit-preflight.sh` when `is_background_agent` is true (Cursor exposes that only on stdin JSON to the hook, not as an env var). `RUNTIME_DEVPUSHES` is a conservative DEFAULT, never probed — a `git push --dry-run` sends no ref-update, so a protected branch's pre-receive hook never fires and a false-positive would strand a cloud session on a `dev` checkout. `runtimeGithubCli` is the one live probe (`gh auth status`). An explicit falsy primitive (`CI=false`, `GITHUB_ACTIONS=false`) means ABSENCE, not ambiguity — treating it as ambiguous would cost a laptop its worktree model; only a non-truthy, non-falsy value goes `UNKNOWN`.
134
+ - **One landing routine for every dev write:** `pushToDev` (`.bkit/core/engine/commands/land.ts`) builds the commit in a throwaway `.worktrees/_land-{FID}` off fresh `origin/dev`, then `git push origin HEAD:dev`. Never touches the main checkout (no collision with parallel closes or uncommitted work); never pushes local-only `dev` commits. Runs no git hooks (pre-commit / pre-push skipped, logged): it lands docs / logs / ledger files only, under `[skip ci]`. `dev` moved — before the push (`[rejected] … (fetch first|non-fast-forward)`) or while it was in flight (`[remote rejected] … (incorrect old value provided|cannot lock ref …)`) → rebuild, push again, up to `LAND_ATTEMPTS`. A server refusal (any other `[remote rejected]`, `returned error: 403`, a `GH0nn` rule) → the caller's refused route. A push with no server answer (network, credentials) → the caller, nothing landed, no PR.
135
+ - `bkit branches land`: design / plan close (`merge --squash -X ours {BRANCH}`, `docs({FID}): {phase} DONE bkit [skip ci]`); refused → PR merge.
136
+ - `bkit workflows close --flush`: ship close, book carried in (`docs({FID}): ship DONE bkit [skip ci]`); refused → `ship-close/{FID}` PR.
137
+ - `bkit workflows handover --flush` (ship Failure Path) / `--push` from `dev` / `main` / detached (design / plan / build / debug Failure Path): `chore({FID}): {phase} FAILED bkit [skip ci]`; refused → record stays in the run's tree for the next run of `{FID}`. From a `dev` / `main` / detached checkout only the run's own record is carried (§ Failure Path), then handed back.
138
+ - `bkit roadmap mirror`: build / debug; an attempt that committed nothing never counts as mirrored.
139
+ - `bkit branches land` reads `RUNTIME_DEVPUSHES` from the run's `runtime-resolved` row (no row → fresh detect). It picks the default `{BRANCH}` (`true` → `feat/{FID}`, `false` → the current branch) and gates only what surrounds the landing: stray-artifact check, local `dev` fast-forward, worktree + `feat/{FID}` teardown.
140
+ - **PR-mode design/plan closes MUST push before `bkit prs open`:** PR creation and `gh pr merge` act on the REMOTE, so a close commit that is only committed locally never enters the PR and never reaches `dev`. The direct push lands one commit built off `origin/dev` and is unaffected; the PR branch produces two local commits (`chore({FID}): close-workflow` carrying the `status.jsonl` rows and close telemetry, then `docs({FID}): {phase} roadmap update` carrying `.bkit/issues.jsonl` + `docs/roadmap.md`) and needs an explicit `bkit branches push --mode=feature` to publish them. Placed after the STRAY guard so nothing unvetted is published, and before `bkit prs open --existing=reuse`. Build/debug close pushes the feature branch already. Omitting it silently loses every design/plan close on the PR path.
141
+ - **`bkit workflows close` runs in the worktree, before the squash, in both close modes:** the `workflow-done` row and the telemetry rows ride the `chore({FID}): close-workflow` commit on `feat/{FID}`, so the squash (direct push) or the PR carries them to `dev`. `status.jsonl` and `.bkit/stats.jsonl` are `merge=union`, so the squash concatenates them with `dev`'s copies.
137
142
  - **`[skip ci]` scope:** deliberate `bkit [skip ci]` on docs-only commit SUBJECTS is the CI-minutes convention and stays. The defect it is confused with is a squash merge whose DEFAULT body concatenates the head branch's commit subjects and inherits a token — hence `bkit prs scan-body` scans the BODY only, and every close passes an explicit `--body ""`.
138
143
  - **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.
139
144
  - **`--delete-branch` is not used by the design/plan PR close:** `gh` also deletes the LOCAL branch, which fails when that branch is checked out in a worktree (`git branch -D` refuses) and returns non-zero after a successful merge; in adopt mode it checks out the base first, stranding a cloud session on `dev`. Head-branch cleanup relies on the repo's auto-delete-head-branches setting.
140
- - **Adopt mode does no `git worktree add`:** a claude.ai cloud session's proxy restricts `git push` to the current working branch, so minting `feat/{FID}` would produce a branch it cannot push. `RUNTIME_WORKTREES=false` therefore 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.
141
- - **Ship Step 13 switches with `bkit branches switch`:** Steps 14-15 operate at `REPO_ROOT` assuming `dev` stays checked out. `branches switch` asserts the double guard itself (`--dev-pushes=true` with `--worktrees=false` → exit 15) and holds the dev lock across the switch.
145
+ - **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.
146
+ - **Ship never checks out `dev`:** Step 13 `bkit branches sync-dev` fetches and fast-forwards local `dev` without a checkout (`git merge --ff-only` + frozen install only when the main checkout is on `dev` and `dev` moved). Local-only `dev` commits → listed with the publish command, never pushed (unreviewed work). Step 14 stays in the feature worktree until the close lands; the close then removes it and `cd`s to `REPO_ROOT`.
142
147
  - **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 additive, none folded. Written by `bkit runtime row` and `bkit prs transport-row`; read back by `bkit runtime assert` and `bkit prs cross-check`.
143
148
  - **`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 / branch parsing as `bkit fids parse`); 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, safe `^[a-z0-9][a-z0-9-]*$` for the no-tracker + branch-derive fallback, tracker-agnostic `^([0-9]+|[a-z]+-[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 must resolve `{ISSUE_ID}` too — from the `{FID}` slug (github: leading numeric segment; linear: first two dash-segments, uppercased), each behind its own allowlist. A fallback that recovers only `{FID}` is dead code on any tracker-wired repo: the Step 1 comment keys every tracker call on `{ISSUE_ID}` and Gate 1 asserts it non-empty, so the run reaches **Failure Path** whatever `{FID}` says. 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.
144
149
  - **Step 1 FID check in every phase workflow:** design, plan, build, debug and ship run `bkit fids check` on the resolved `FID` at Step 1 — whichever sub-step resolved it (session prompt, branch, existing logs, mint) and under every tracker, `none` included (the safe allowlist). A bad `FID` then fails before any work, not at `bkit prs open`, which keeps its own check as a backstop.
@@ -147,8 +152,8 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
147
152
  - **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.
148
153
  - **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.
149
154
  - **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 B2 conflict-resolve stage and the Step 8 bookkeeping 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.
150
- - **Failure Path never calls `bkit runtime assert`:** its contract is "route a non-zero return to the **Failure Path**", which is a self-loop from inside one. `--dev-pushes` goes on `workflows fail` / `workflows handover --flush` only when the held `{RUNTIME_DEVPUSHES}` is `true`; without it they take the least-capable branch — the same one `UNKNOWN` gets — so an unresolved runtime still lands the record on the current branch rather than attempting a `dev` push it cannot make.
151
- - **Failure Path reconciles branch-side artifacts before staging:** the deferred sweep and the handover subagent both `cd` into `{WORKTREE_PATH}`, which is not `BOOK_ROOT` in mint mode, and a failed ship never merges the branch — without the copy those artifacts die with the worktree. `bkit workflows handover --flush` copies the worktree's `*.md` logs that the book root lacks and unions the ledgers line-wise (the `bkit ledgers union` code) rather than copying them: both trees hold rows the other does not. `--worktree=` names the worktree; without it, `.worktrees/{FID}`.
155
+ - **Failure Path never calls `bkit runtime assert`:** its non-zero route would loop into itself. `workflows fail` / `handover --push` / `--flush` behave identically in every runtime: record written in the run's tree, then pushed on the feature branch or landed via the throwaway `origin/dev` checkout; refused → stays in the run's tree for the next run of `{FID}`. In a cloud container that tree dies with it, so a refused record is lost.
156
+ - **Ship's dev commits carry the book:** ship books in `{WORKTREE_PATH}` (`BOOK_ROOT`); a failed ship never merges. Close and Failure Path copy the book's `*.md` logs the throwaway checkout lacks and union ledgers line-wise (`bkit ledgers union` code; each tree holds rows the other lacks). `handover --worktree=` names the book; default = current tree.
152
157
  - **`context-fetch` blocks are selected by ordinal, not by `context` + name:** two blocks may legitimately share a pair — the context-coverage advisory tells consumers a second test lane needs its own `context=e2e` block, and naming is optional — and matching on the pair splices both bodies into one block and writes them to one artifact path. `bkit context list-blocks` numbers every block (`idx`) in one enumeration pass and `bkit context run-block --idx=` runs exactly that one, so selection is total; the artifact path only grows the ordinal when the pair actually repeats, keeping the documented `context-<context>-<name>-<attempt>.md` shape for every single-block context.
153
158
  - **Unknown `context-fetch` context is never run:** `run-block` reports `not-run` with the bad `context=` named. Running it would make a paid API call in the `web` case and write its output under an empty prefix — a path the `context-*` glob cannot match, dropping the artifact from `artifacts` and from `FETCH_VERDICT`. The narration and the behaviour agree.
154
159
  - **`bkit context finalise` re-reads the configured contexts:** `contextsConfigured` comes from the context file at finalise time, never from a value an earlier block printed — an inherited value records `[]` whenever it is lost between blocks, which is telemetry claiming no contexts were configured on a run that fetched them, and a tracker comment marking all five `NOT CONFIGURED`.
@@ -193,7 +198,7 @@ Every phase command (`design`, `plan`, `build`, `debug`, `ship`) shares skeleton
193
198
  3. Execution Protocol caution block (header bullets — see below)
194
199
  4. Failure Path
195
200
  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`)
196
- 6. Step 2 — Worktree Setup (`bkit worktrees setup`: create / resume / adopt, copy `bkit.worktree.copy` (default `.env`, `.env.local`), install unless `bkit.worktree.install` is false; `bkit workflows start` + `bkit runtime row`; save input; `start-workflow` + `worktree-setup` step entries committed on `feat/{FID}`)
201
+ 6. Step 2 — Worktree Setup (`bkit worktrees setup`: create / resume / adopt; create / resume under `bkit.disk.minFreeGb` free → `max` disk-prune steps first, still under → exit 12 (`.bkit/templates.md` § Disk prune); copy `bkit.worktree.copy` (default `.env`, `.env.local`), install unless `bkit.worktree.install` is false; `bkit workflows start` + `bkit runtime row`; save input; `start-workflow` + `worktree-setup` step entries committed on `feat/{FID}`)
197
202
  7. Phase-specific steps (subagent invocations, gates, per-step new comment post)
198
203
  8. Summary step (subagent → commit → push → verdict)
199
204
  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)
@@ -205,9 +210,9 @@ Every phase command (`design`, `plan`, `build`, `debug`, `ship`) shares skeleton
205
210
 
206
211
  **Pre-worktree git scope:** Step 1 + Step 2 pre-worktree guard on originating branch (often `dev`). Stage the bookkeeping allow-list only (`bkit ledgers commit --only-if-dirty-tracked --scope=core`: FID log dir + ledgers — NEVER whole `docs/plans/` tree). never `git add -A` until `cd "$WORKTREE_PATH"` — sweeps unrelated user edits into workflow commit → rides feat → dev on merge. Post-worktree (Step 3+) `git add -A` fine; cwd = sandbox. `git worktree add` does not inherit dirty state.
207
212
 
208
- **Worktree isolation (no Step 1 dev sync gate):** all phases Step 1: ZERO commits on `dev`; does not assert local `dev` synced with `origin/dev`. Step 1 only fetches `origin dev` (`bkit repo info --fetch`, which reports `behindDev`); work in `.worktrees/{FID}` on `feat/{FID}`, cut from or rebased onto `origin/dev` in Step 2 (debug is the exception — it adopts rather than mints, and adopts in place with no rebase when `feat/{FID}` is gone). Local `dev` ahead-of-origin irrelevant at start — Close reconciles at merge (`git pull --ff-only origin dev` before squash-merge design/plan; ship Step 13 `bkit branches switch` when switching post-merge). Rationale: blocking on unpushed local `dev` forces manual intervention before isolated work; those commits do not affect worktree until Close merges back.
213
+ **Worktree isolation (no Step 1 dev sync gate):** all phases Step 1: ZERO commits on `dev`; does not assert local `dev` synced with `origin/dev`. Step 1 only fetches `origin dev` (`bkit repo info --fetch`, which reports `behindDev`); work in `.worktrees/{FID}` on `feat/{FID}`, cut from or rebased onto `origin/dev` in Step 2 (debug is the exception — it adopts rather than mints, and adopts in place with no rebase when `feat/{FID}` is gone). Local `dev` ahead-of-origin irrelevant at start and at close: every close lands from a throwaway `.worktrees/_land-{FID}` off fresh `origin/dev` and never pushes local-only `dev` commits; afterwards local `dev` fast-forwards only on a pure fast-forward, without a checkout (design / plan: `bkit branches land`; ship: Step 13 `bkit branches sync-dev`). Rationale: blocking on unpushed local `dev` forces manual intervention before isolated work; those commits never reach the worktree or the close.
209
214
 
210
- **Branch placement:** `design`/`plan`/`build`/`debug` write + commit `status.jsonl` on `feat/{FID}` — no mid-lifecycle `dev` push; state reaches `dev` once via Close squash-merge (design/plan) or ship PR squash (build/debug). `ship` Steps 1-8 on `feat/{FID}`, Steps 9-13 on `dev`. `cloud` = stateless dispatcher — no `status.jsonl` (tracker comment only). See § `status.jsonl` — workflow state SoT.
215
+ **Branch placement:** `design`/`plan`/`build`/`debug` write + commit `status.jsonl` on `feat/{FID}` — no mid-lifecycle `dev` push; state reaches `dev` once via Close squash-merge (design/plan) or ship PR squash (build/debug). `ship` books every step in the feature worktree (`BOOK_ROOT` = `{WORKTREE_PATH}`) and never checks out `dev`; pre-merge rows ride the PR, post-merge rows land with the Step 14 close commit. `cloud` = stateless dispatcher — no `status.jsonl` (tracker comment only). See § `status.jsonl` — workflow state SoT.
211
216
 
212
217
  ### Execution Protocol — header bullets
213
218
 
@@ -223,16 +228,16 @@ Caution-block bullets of the 6 workflow files, in file order. Every bullet carri
223
228
  | **`Failures`** | all 6 | Any step, tool, command failure, or gate that cannot pass → **Failure Path**. |
224
229
  | **Friction** | all 6 | Confirm prompts, manual installs, rework, repeated tool failures, destructive backouts → append `.bkit/friction.jsonl` rows → continue or escalate; never replaces **Failure Path**. |
225
230
  | **Placeholders** | all 6 | Assert required `{PLACEHOLDERS}` non-empty before tool calls → else **Failure Path**. auto and plan name their own placeholders; auto derives `{OWNER}` / `{REPO}` from `{OWNER_REPO}` at Step 1. |
226
- | **Commands** | all 6 | Blocks run `"{BKIT}" <noun> <verb> --flag=value`; `{BKIT}` = `bkit` printed by Step 1 `repo info` (before it, the lookup expression); stdout is one JSON object; exit non-zero with no `Route:` → **Failure Path**; exit 80 → mapped MCP tool (auto: **Failure Path**); exit 81 → end turn, re-run block; a flag still holding a literal `{PLACEHOLDER}` exits 2. ship adds: `--dev-pushes` only when `RUNTIME_DEVPUSHES` = true. |
231
+ | **Commands** | all 6 | Blocks run `"{BKIT}" <noun> <verb> --flag=value`; `{BKIT}` = `bkit` printed by Step 1 `repo info` (before it, the lookup expression); stdout is one JSON object; exit non-zero with no `Route:` → **Failure Path**; exit 80 → mapped MCP tool (auto: **Failure Path**); exit 81 → end turn, re-run block; a flag still holding a literal `{PLACEHOLDER}` exits 2. |
227
232
  | **Finish** | 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`. Exit 5 or 6 → re-ask `reask.agent` for its header only, re-run the block; still non-zero → **Failure Path**. |
228
233
  | **Resume** | design, plan, build, debug, ship | On start, fold status.jsonl; pick up after last `DONE` step in active `IN_PROGRESS` workflow. |
229
234
  | **Status** | 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 `subPlan`, debug a `workflow-meta` `debugAttempt`. |
230
- | **Locks** | design, plan, build, debug, ship | Step 1 takes the per-feature `.lock` (`bkit locks acquire`); released at close and in Failure Path. Existing lock: holder `IN_PROGRESS` with a step <30min ago → **Failure Path**; any other holder's lock reclaimed. design, plan, ship add the **Dev lock** sentence (§ Cross-step invariants). |
235
+ | **Locks** | design, plan, build, debug, ship | Step 1 takes the per-feature `.lock` (`bkit locks acquire`); released at close and in Failure Path. Existing lock: holder `IN_PROGRESS` with a step <30min ago → **Failure Path**; any other holder's lock reclaimed. |
231
236
  | **Status branch** | 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. |
232
237
  | **Worktrees** | 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**. |
233
238
  | **gh MCP fallback** | 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 calls stay on MCP. One identical line in all five. |
234
239
  | **External tools** | auto | `gh` reads the PR and its CI run inside `bkit runs context`; exit 80 → **Failure Path**; tracker calls stay on MCP. |
235
- | **Tracker** / **Labels** / **Comments** | all 6, once per tracker block | Tracker MCP tools; writes best-effort, retry once after 5s. Phase labels mutually exclusive; `bkit:auto`, `bkit:failed`, `bkit:debug` additive (§ Tracker Integration). Post the `comment` a step's `bkit` block prints as a new comment before its gate; every gate includes `Issue comment attempted (Step N section)` without listing it; never edit prior content (§ Comment Lifecycle). |
240
+ | **Tracker** / **Labels** / **Comments** | all 6, once per tracker block | Tracker MCP tools; 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). Post the `comment` a step's `bkit` block prints as a new comment before its gate; every gate includes `Issue comment attempted (Step N section)` without listing it; never edit prior content (§ Comment Lifecycle). |
236
241
  | **Timeouts** | all 6 | Workflow or subagent run > 3600 seconds → **Failure Path**. |
237
242
  | **Limits** | build, debug, ship | Attempt caps by name from `bkit counters max` / `bkit counters route --limit=`. |
238
243
  | **Modes** | debug | `PUSH_MODE` (`PR|LOCAL`) and `DEBUG_MODE` (`NORMAL|SOAK`), both set at Step 1. |
@@ -245,12 +250,11 @@ Caution-block bullets of the 6 workflow files, in file order. Every bullet carri
245
250
  <!-- prettier-ignore -->
246
251
  | Invariant | Rule |
247
252
  | --- | --- |
248
- | **Locks** | Step 1 takes the per-feature `.lock` with `bkit locks acquire --kind=workflow` once `FID` is resolved; hold `token` as `{LOCK_TOKEN}`. Lock path is **absolute** (`$REPO_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock`; ship with `RUNTIME_DEVPUSHES` != true: `$BOOK_ROOT/…`) so acquire/release resolve to the same inode regardless of cwd. Lock line `{at} {workflow} {fid} {token}`. Existing lock → its owning workflow's folded status.jsonl decides: `IN_PROGRESS` + last step <30min → refused (`workflow already running for {FID}`) → Failure Path; any other holder (`DONE` / `FAILED`, idle `IN_PROGRESS`, no run in the log) is reclaimed as soon as it is idle; the lock file's own age is not checked. Released in Close Workflow (`bkit locks release --token=`) and Failure Path (`bkit workflows fail --token=`, skipped when `{LOCK_TOKEN}` is empty — the run never took the lock). Release removes only the caller's own lock (another owner's stays, exit 4); a lock file that survives removal exits 5 → `Lock removal failed`. |
249
- | **Dev lock** | Repo-global `$REPO_ROOT/.bkit/.dev.lock` (gitignored), held ONLY across a **dev critical section** — any block that checks out, stages, commits, or pushes `dev` in the **main checkout**. Scope is cross-FID: the per-FID `.lock` guards two runs of the same feature, but concurrent runs of DIFFERENT features share `dev`, the main working tree, `.git/config` and `.bkit/stats.jsonl`, and corrupt each other with no per-FID contention. Sites: `design` and `plan` close-workflow squash; `build` / `debug` close dev-side roadmap mirror (`--deadline=60`, skipped when busy); `ship` Step 13 (`bkit branches switch`), Step 15 (close), Failure Path (`--deadline=60`, skips its dev ops when busy). Acquire is atomic (`bkit locks acquire --kind=dev`, `O_EXCL` create) and waits up to `--deadline` (default 600s); a holder older than 900s is presumed dead and reclaimed. Release via `trap` running `bkit locks release --kind=dev --token=` on `EXIT`, so every `exit 1` inside the section releases; release never removes another holder's lock. Holder line `{at} {workflow} {fid} {token}` — reported verbatim on contention. Worktree-phase work stays fully parallel; only the dev sections serialise. |
253
+ | **Locks** | Step 1 takes the per-feature `.lock` with `bkit locks acquire --kind=workflow` once `FID` is resolved; hold `token` as `{LOCK_TOKEN}`. Lock path is **absolute** (`$REPO_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock`, ship included — the lock file is gitignored and never rides a commit) so acquire/release resolve to the same inode regardless of cwd. Lock line `{at} {workflow} {fid} {token}`. Existing lock → its owning workflow's folded status.jsonl decides: `IN_PROGRESS` + last step <30min → refused (`workflow already running for {FID}`) → Failure Path; any other holder (`DONE` / `FAILED`, idle `IN_PROGRESS`, no run in the log) is reclaimed as soon as it is idle; the lock file's own age is not checked. Released in Close Workflow (`bkit locks release --token=`) and Failure Path (`bkit workflows fail --token=`, skipped when `{LOCK_TOKEN}` is empty — the run never took the lock). Release removes only the caller's own lock (another owner's stays, exit 4); a lock file that survives removal exits 5 → `Lock removal failed`. |
250
254
  | **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: `bkit prs update-branch` moves the head immediately 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. |
251
- | **Artifact tree** | A subagent's artifact is asserted **under the working directory its dispatch supplied** — `{WORKTREE_PATH}` for worktree-phase agents, the main checkout for ship's deferred-sweep / update-docs / summary agents. 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`. |
255
+ | **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`. |
252
256
  | **Main-checkout staging** | Every `git add` **and** `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 work a user staged themselves. Worktree-phase `git add -A` is unrestricted — that tree holds only this feature's work. |
253
- | **Close squash** | design / plan local close (`RUNTIME_DEVPUSHES=true`): non-zero `git merge --squash` → stop; nothing committed or pushed, `feat/{FID}` and worktree kept. Git refuses the squash when another session's uncommitted edit touches a squashed file, or (non-fast-forward) when anything is staged. Before commit, staged `{FID}-design.md` / `{FID}-plan.md` (and sub-plans) blob must equal `feat/{FID}`'s — presence on `dev` proves nothing on a re-run, and `-X ours` keeps `dev`'s side of a conflicting hunk. Commit via `bkit ledgers commit --squash-of=feat/{FID}`: pathspec = bookkeeping allow-list + paths the squash brought in → another session's staged file stays staged, out of the close commit. Worktree / branch deletion only after the push. Failed blob check → squash stays staged in the main checkout for a human to clear. |
257
+ | **Close squash** | design / plan close, every runtime: `bkit branches land` fetches `origin/dev`, adds a detached `.worktrees/_land-{FID}` there, squashes `{BRANCH}` into it with `-X ours`, then appends back any `.jsonl` row the branch added that the squash dropped (a ledger without `merge=union`, e.g. a consumer's `.bkit/friction.jsonl`). Non-zero squash, staged non-doc files (`CLOSE_DOCS`), or a staged `{FID}-design.md` / `{FID}-plan.md` (and sub-plans) blob that differs from the branch's → stop; nothing pushed, branch and worktree kept — presence on `dev` proves nothing on a re-run, and `-X ours` keeps `dev`'s side of a conflicting hunk. Roadmap row, then commit via `bkit ledgers commit --squash-of={BRANCH}` and `git push origin HEAD:dev`. Push rejected because `dev` moved → drop the throwaway worktree, refetch, rebuild, push again: `LAND_ATTEMPTS` pushes, waits doubling from `LAND_BACKOFF_START_S` to `LAND_BACKOFF_CAP_S` with jitter; all used → exit 8, nothing landed. A push with no server answer → exit 8, nothing landed, no PR. A server refusal → PR close (roadmap commit on the branch in the checkout holding it, push, open or reuse the PR, squash-merge; a refused merge on an OPEN PR → `bkit prs update-branch` and retry on the same schedule, then exit 17 with the PR left open). The throwaway worktree is removed on every path. `RUNTIME_DEVPUSHES=true` only, after landing: local `dev` fast-forwards to the landed commit when that is a pure fast-forward (`merge --ff-only` when the main checkout is on `dev`, else the pointer alone); local-only commits on `dev` or git refusing (an uncommitted edit the move would overwrite) skip it with a log line, never failing the close; then the workflow-created worktree and `feat/{FID}` go. Nothing is deleted until `origin/dev` holds the branch's work: any file the branch changed that differs on `origin/dev` (`.jsonl`: any line the branch added that `origin/dev` lacks; `docs/roadmap.md` excepted) → exit 18, branch and worktree kept; uncommitted or untracked files in `.worktrees/{FID}` → close succeeds, worktree and branch kept (`worktree.reason: uncommitted`) with the file list logged. The main checkout is never written to: the `close-transport` row is written only when the run's own checkout is the branch (`RUNTIME_DEVPUSHES=false`); otherwise its `shape` / `sha` / `scan` go to a log line and the cross-check reads the landed commit's copy. Gate 12 reads `status.jsonl` from `origin/dev` (`bkit steps gate --ref=origin/dev`), so it passes whether or not local `dev` moved. |
254
258
 
255
259
  ### `status.jsonl` — workflow state SoT
256
260
 
@@ -264,8 +268,8 @@ Caution-block bullets of the 6 workflow files, in file order. Every bullet carri
264
268
  | Workflow | Location | Mechanism |
265
269
  | --- | --- | --- |
266
270
  | `build`, `debug` | `feat/{FID}` worktree (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`) | Written + committed on `feat/{FID}` via the per-step commits. no mid-lifecycle `dev` push (Close or Failure Path). State reaches `dev` once, at ship's PR squash-merge. |
267
- | `design`, `plan` | `feat/{FID}` worktree (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`) | Written + committed on the throwaway `feat/{FID}` via the per-step commits — exactly like `build`/`debug`. no mid-lifecycle `dev` push; status + generated docs reach `dev` together via the **Close-Workflow squash-merge** (`docs({FID}): {phase} DONE`). Failure Path appends `workflow-failed` to the retained worktree copy (no `dev` push); the tracker comment carries the failure signal. |
268
- | `ship` | `$BOOK_ROOT/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` — main checkout when `RUNTIME_DEVPUSHES=true`, else the shipped branch's tree (`bkit status path --dev-pushes`) | Pre-merge rows ride the PR in the Step 8 bookkeeping commit; post-merge rows land with the Close commit (`dev`, or a `ship-close/{FID}` PR) or the Failure Path flush. Ship is terminal, so its close commit + push is the legitimate state landing. |
271
+ | `design`, `plan` | `feat/{FID}` worktree (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`) | Written + committed on the throwaway `feat/{FID}` via the per-step commits — exactly like `build`/`debug`. no mid-lifecycle `dev` push; status + generated docs reach `dev` together via the **Close-Workflow squash-merge** (`docs({FID}): {phase} DONE`). Failure Path appends `workflow-failed` to the retained worktree copy, then `bkit workflows handover --push` commits and pushes the record on the feature branch (open PR → not pushed; no `dev` push); the tracker comment carries the failure signal. |
272
+ | `ship` | `$BOOK_ROOT/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` — the shipped branch's tree (`{WORKTREE_PATH}`; `bkit status path` run there) | Pre-merge rows ride the PR in the Step 8 bookkeeping commit; post-merge rows land with the Close commit (`dev`, or a `ship-close/{FID}` PR) or the Failure Path flush, each built in a throwaway `origin/dev` checkout carrying the book. Ship is terminal, so its close commit + push is the legitimate state landing. |
269
273
  | `cloud` | — (none) | Stateless phase dispatcher — writes no `status.jsonl` and makes no `dev` commit; the run is recorded only by its tracker comment. The dispatched skill owns its own state/FID/worktree. |
270
274
 
271
275
  Rationale: per-run state on `feat/{FID}` removes dev↔feat divergence at source; NDJSON+union merge-safe regardless. `design`/`plan` on throwaway `feat/{FID}` like `build`/`debug` — status + docs reach `dev` via single Close squash-merge; only doc-link URLs in tracker comments hard-coded to `dev`. `cloud` = pure dispatcher — no worktree, no state, no `status.jsonl` (tracker comment only). Design/plan close `dev` commit = docs/telemetry-only, carries `bkit [skip ci]`, no CI dispatched. (`audit` not built; per design follows design/plan feat pattern.)
@@ -282,9 +286,9 @@ Rationale: per-run state on `feat/{FID}` removes dev↔feat divergence at source
282
286
  | `workflow-failed` | `{type, workflow, at}` | Terminal — sets the run's `status` to `FAILED`. |
283
287
  | `runtime-resolved` | `{type, workflow, at, runtime, runtimeWorktrees, runtimeDevPushes, runtimeGithubCli, runtimeGithubCliExit, runtimeGithubCliErr, baseSha}` | Step-2 (Worktree Setup) record of the runtime capability table for this run — the first step `{FID}`/`WORKTREE_PATH` are resolved. Written by `bkit runtime row --file=` (detects, then appends), read back by `bkit runtime assert` (exit 4 no row, 5 an unresolved field). Not folded (unrecognised `type` — ignored, no-op) — later steps re-read `runtimeGithubCli` from this row instead of re-probing `gh`; shell state does not survive a Bash-tool-call boundary, so this row is the durable cross-block record. `baseSha` = `git merge-base origin/dev HEAD` for the design/plan worktree (`--base-sha=`, from `bkit worktrees setup`'s `baseSha`), recorded after Step 2's worktree/rebase arm settles; Close Workflow reads it back to stamp the canonical doc's `bkit:anchor` block (§ Anchor Block) rather than recomputing against a `dev` that has since advanced. Empty for build, debug, ship. |
284
288
  | `transport-fallback` | `{type, from, to, reason, assertedBy, at}` | One gh->MCP transition (bounded max 1/run). `from` = the gh command that was unavailable/unauthed; `to` = the mapped MCP tool used instead; `assertedBy` = how the fallback's success was independently re-read. Not folded. Emitted by `bkit prs transport-row --kind=fallback`; read back by `bkit prs cross-check` at Close Workflow — an `mcp` close with `runtime-resolved.runtimeGithubCli=false` and no row here is a Failure Path. |
285
- | `close-transport` | `{type, shape, sha, scanResult, at}` | Close Workflow's own audit-trail entry. `shape` = which close shape ran — `local` (design/plan local squash-merge + `dev` push), `pr` (design/plan PR squash-merge when `RUNTIME_DEVPUSHES` != true), `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
+ | `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`. |
286
290
  | `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. |
287
- | `ship-merge-ci` | `{type, workflow, at, sha, run, verdict, reason}` | Step 15's squash-merge CI verdict, written before routing: `verdict` `PASS|FAIL`, `reason` empty on PASS. A red merge is recorded, never inferred from a missing close row. Not folded. |
291
+ | `ship-merge-ci` | `{type, workflow, at, sha, run, verdict, reason}` | Step 14's squash-merge CI verdict, written before routing: `verdict` `PASS|FAIL`, `reason` empty on PASS. A red merge is recorded, never inferred from a missing close row. Not folded. |
288
292
  | `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. |
289
293
  | `ship-revalidate-dispatch` | `{type, workflow, at, head, probe, reason, dispatched, attempts}` | One Step 9 wait. `head` = `VALIDATED_HEAD`; `probe` = presence-probe outcome (`found`/`none`/`err`); `reason` = `head-move` or `gate-refusal`; `dispatched` = whether `bkit runs wait --dispatch-if-absent` ran `gh workflow run {bkit.ciWorkflow}` after the probe found no run. Written by `bkit status row`, not folded. Counted by `bkit counters rows` since the run's `workflow-started` row to bound gate-refusal re-entry against `MAX_REVALIDATE_ATTEMPT`. |
290
294
 
@@ -297,7 +301,7 @@ Rationale: per-run state on `feat/{FID}` removes dev↔feat divergence at source
297
301
  <!-- prettier-ignore -->
298
302
  | Event | Command |
299
303
  | --- | --- |
300
- | `workflow-started` | `bkit workflows start --lock-held --token=` (Step 2) — appends only when the latest run is not this workflow `IN_PROGRESS`; prints `run` |
304
+ | `workflow-started` | `bkit workflows start --lock-held --token=` (Step 2; ship Step 1, right after its lock) — appends only when the latest run is not this workflow `IN_PROGRESS`; prints `run` |
301
305
  | `step-done` | `bkit steps done --step= [--verdict= --failures= --attempt= --artifact= --field=K=V]` — `parentSha` captured before the step's commit; `--commit=none` writes the row only |
302
306
  | `workflow-meta` | `bkit status meta` (`--debug-mode` / `--push-mode` / `--debug-attempt` / `--plan-source` / `--soak-entry` / `--opened-pr`) |
303
307
  | `workflow-done` + telemetry | `bkit workflows close` |
@@ -411,13 +415,13 @@ Cross-block routing values re-read from `status.jsonl` with `bkit status route -
411
415
 
412
416
  ### Concurrency lock
413
417
 
414
- `docs/plans/{YYYYMM}/logs/{FID}/.lock` under the main checkout (ship with `RUNTIME_DEVPUSHES` != true: under `$BOOK_ROOT`) = one line `{at} {workflow} {fid} {token}`. **Absolute** path — acquire/release same inode from main repo or worktree. Step 1 `bkit locks acquire --kind=workflow --workflow= --fid=` (creates the log dir, resolves `month`, prints `token`); Step 2 `bkit workflows start --lock-held --token=` checks it is still ours (exit 6 otherwise); released by `bkit locks release --token=` (Close Workflow) and `bkit workflows fail --token=` (Failure Path).
418
+ `docs/plans/{YYYYMM}/logs/{FID}/.lock` under the main checkout (every workflow, ship included) = one line `{at} {workflow} {fid} {token}`. **Absolute** path — acquire/release same inode from main repo or worktree. Step 1 `bkit locks acquire --kind=workflow --workflow= --fid=` (creates the log dir, resolves `month`, prints `token`); Step 2 (ship: Step 1, right after the lock) `bkit workflows start --lock-held --token=` checks it is still ours (exit 6 otherwise); released by `bkit locks release --token=` (Close Workflow) and `bkit workflows fail --token=` (Failure Path).
415
419
 
416
420
  **Staleness rule** (`bkit locks acquire`): read the holder's status.jsonl via fold (`design`/`plan`/`build`/`debug` prefer the `feat/{FID}` worktree copy, else the main checkout). (`cloud` holds no lock, writes no status.) `IN_PROGRESS` + last step <30min idle → refused, Failure Path. Otherwise the lock is reclaimed at once, whatever the lock file's age — `reclaimed.reason` = `finished` (`DONE`/`FAILED`), `stale` (`IN_PROGRESS` idle), `orphaned` (no run in the log). Timestamps parse as UTC (`Date.parse`), never through local-time `date`.
417
421
 
418
422
  ### Comment Lifecycle
419
423
 
420
- Every workflow step posts new tracker comment via inline `comment-post-step` block (per-tracker `github`/`linear`/`none`, resolved at install; § Tracker Blocks). never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior content. Each step independent — no comment-ID carry-forward, no body concatenation. `bkit issues comment` builds every body below (`--kind=step|failure|handover`, header fields in flag order, `###### bkit:generated` first, a copied whole-line cut marker defused, stderr fenced) and prints it; the tracker MCP call posts it — the command never touches the tracker.
424
+ Every workflow step posts new tracker comment via inline `comment-post-step` block (per-tracker `github`/`linear`/`none`, resolved at install; § Tracker Blocks). never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior content. Each step independent — no comment-ID carry-forward, no body concatenation. `bkit issues comment` builds every body below (`--kind=step|failure|handover|audit`, header fields in flag order, `###### bkit:generated` first, a copied whole-line cut marker defused, stderr fenced) and prints it; the tracker MCP call posts it — the command never touches the tracker.
421
425
 
422
426
  **Step 1 (first comment):**
423
427
 
@@ -482,6 +486,19 @@ Stderr: {last 20 lines if shell}
482
486
  {handover.md content verbatim}
483
487
  ```
484
488
 
489
+ **Audit summary (`@bkit-audit-generate`, issue named in its input; § Audits):**
490
+
491
+ ```comment
492
+ ###### bkit:generated
493
+ ### Audit Summary: {slug} - Status: {STATUS} - Findings: CRITICAL {n} · HIGH {n} · MEDIUM {n} · LOW {n}
494
+ Report: [{slug}.md](https://github.com/{OWNER_REPO}/blob/{BRANCH}/docs/audits/{YYYYMM}/{slug}.md)
495
+ {final summary, Stopped through Recommended Next Step}
496
+ ```
497
+
498
+ The audit agent never commits, so the `Report` link resolves once its caller pushes the report to `{BRANCH}`. A detached HEAD has no branch to link at: the path is written unlinked.
499
+
500
+ **Section links:** `--artifact=<path>#<Heading>` links the rendered doc at that heading — `[{file} § {Heading}](…/blob/{ref}/{path}#{anchor})`. `bkit issues comment` builds the anchor GitHub gives the heading (lowercased, punctuation dropped, spaces to hyphens); a repeated heading's later copies take `-1`, `-2`, so the link names the first. A renamed heading leaves the link opening the doc at the top.
501
+
485
502
  ### Tracker Writes Are Best-Effort
486
503
 
487
504
  Tracker write calls (issue update, comment post) = observability, not gates. never block, hang, or fail workflow on tracker write failure. Tracker reads (issue read, list comments) remain authoritative.
@@ -697,8 +714,7 @@ Then assert each Update/Create artifact exists, non-empty. Empty → **Failure P
697
714
  | Grill rounds | 10 | `/bkit-design` Step 3 interview cap; literal in the step, not in `THRESHOLDS` |
698
715
  | Step timeout | 3600s | Any workflow or subagent run exceeding this → Failure Path; `/bkit-design` Step 3 time waiting on human answers does not count |
699
716
  | 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`) |
700
- | Dev lock stale threshold | 900s | `.bkit/.dev.lock` age at which a holder is presumed dead → reclaim and retry (`SHIP_DEV_LOCK_STALE_S`). Bounds the blast radius of a leaked dev lock to 15min |
701
- | Dev lock wait budget | 600s | How long a dev critical section waits for the lock before Failure Path with the holder line (`SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S`). Ship's Failure Path and the build / debug dev-side roadmap mirror pass `--deadline=60` and skip their dev ops rather than hard-failing |
717
+ | 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 |
702
718
  | Ship CI wait | 1800s / 30s | Step 9 completion poll budget / interval (`SHIP_CI_WAIT_TIMEOUT_S` / `SHIP_POLL_INTERVAL_S`) |
703
719
  | Ship presence probe | 6 x 10s | Step 9 run-at-head probe before any dispatch (`SHIP_PROBE_ATTEMPTS` x `SHIP_PROBE_INTERVAL_S`) |
704
720
  | Newest-bkit lookup | 5s / 86400s / 3600s | Registry query limit / answer reuse / failure reuse for the outdated-bkit check (`BKIT_LATEST_LOOKUP_TIMEOUT_S` / `BKIT_LATEST_CACHE_S` / `BKIT_LATEST_RETRY_S`) |
@@ -711,19 +727,25 @@ Every command has `## 🤖 Failure Path` before Step 1. Any step / tool / gate f
711
727
 
712
728
  **Standard failure (always):**
713
729
 
714
- 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 `--dev-pushes`, `--pr=`). State is changed only with a `--token` (an empty one counts as absent: the failure came before Step 1 took the lock): appends `workflow-failed` (nothing when `status.jsonl` does not exist yet), aborts a rebase 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`), `linearState`, `handoverNeeded` (`--max-exceeded`, a sentinel existed, or a debug run in `SOAK`), and the `### Workflow Failure` `comment`. No dev push.
730
+ 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: the failure came before Step 1 took the lock): appends `workflow-failed` (nothing when `status.jsonl` does not exist yet), aborts a rebase 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`), `linearState`, `handoverNeeded` (`--max-exceeded`, a sentinel existed, or a debug run in `SOAK`), and the `### Workflow Failure` `comment`. No dev push.
715
731
  2. Write the labels through the tracker MCP; post `comment`.
716
732
 
717
733
  **Conditional handover** — only when `handoverNeeded` **and** a worktree exists (handover agent `cd`s `{WORKTREE_PATH}`; `/bkit-debug` decides `DEBUG_MODE` at Step 1 before the worktree — a pre-worktree failure goes straight to STOP):
718
734
 
719
735
  3. `@bkit-debug-abort-handover` with prior logs as Read; Write `docs/plans/{YYYYMM}/logs/{FID}/{phase}-handover.md`.
720
- 4. `bkit workflows handover --workflow= --fid= --month= --push`: missing / empty handover → exit 8, nothing committed. Else `git add -A` → commit `docs({FID}): {phase} aborted bkit [skip ci]` → push `--mode=abort`. Open PR on the branch → exit 9, **no push** — the `[skip ci]` abort never lands on a live PR, whose rollup it would empty; remote HEAD kept. `gh` unable to answer → exit 80, nothing pushed → probe via `list_pull_requests`, re-run with `--open-pr=<n>|none`. It prints the `### Workflow Handover` `comment` — blob link at the pushed ref (none when nothing was pushed) + verbatim body — which the orchestrator posts.
736
+
737
+ **Keep the record (always; design / plan / build / debug)** — skipped only when `{WORKTREE_PATH}` is not set (failure before the run had a tree; no row written):
738
+
739
+ 4. `bkit workflows handover --workflow= --fid= --month= --push --worktree="{WORKTREE_PATH}"`, run in the run's tree:
740
+ - **Feature branch:** `git add -A` → commit `docs({FID}): {phase} aborted bkit [skip ci]` (handover or not) → push `--mode=abort`. Open PR → exit 9, **no push** (a `[skip ci]` head empties the PR's check rollup); record stays committed locally. `gh` cannot answer → exit 80, no push → probe via `list_pull_requests`, re-run with `--open-pr=<n>|none`.
741
+ - **`dev` / `main` / detached** (debug adopting `dev` / `main`): nothing staged, committed or pushed from the checkout; half-done code never reaches a shared branch. Only the run's own record is carried into a throwaway `origin/dev` checkout: the `.md` logs it wrote in its log folder, that folder's `.jsonl` lines `HEAD` lacks, and the uncommitted rows of that workflow at or after the run's `workflow-started` in `docs/*.jsonl` / `.bkit/*.jsonl` (not `.bkit/issues.jsonl`; no start row → none) → **one** `chore({FID}): {phase} FAILED bkit [skip ci]` commit, as ship's flush. Refused / out of retries → exit 10; fetch / checkout failure → exit 11; record stays in the checkout. Landed → hand-back removes from the checkout only what was carried, so a later `dev` fast-forward does not stop on it: a carried log identical to the landed copy → removed (untracked) or restored to `HEAD` (tracked); a carried ledger loses exactly the carried lines (equal to `HEAD` → restored; untracked and empty → removed). Staged paths, or a log changed since it landed, stay, logged.
742
+ - Prints the `### Workflow Handover` `comment` (null without a handover): blob link at the pushed ref (none if nothing pushed) + verbatim body; the orchestrator posts it.
721
743
 
722
744
  5. **STOP** — no downstream steps.
723
745
 
724
- **Ship exception:** `/bkit-ship` emits no separate abort commit and no second push. After the optional handover subagent, `bkit workflows handover --workflow=ship --flush [--dev-pushes] --worktree=` reconciles branch-side artifacts (handover, deferred-sweep, ledger rows) into `BOOK_ROOT`, then makes **one** `chore({FID}): ship FAILED bkit [skip ci]` commit and **one** push whose target is `--dev-pushes`-conditional — `dev` under the dev lock (busy → skipped, the record rides the next dev commit) when set, the current branch otherwise. Consequence: it cannot mutate the still-open PR's validated head, so the open-PR guard does not apply to it, and the handover artifact survives on a tree the branch prune cannot take with it. The handover comment is posted only when `handoverNeeded`, linked only where the flush pushed it.
746
+ **Ship exception:** no separate abort commit, no second push. After the optional handover subagent, `bkit workflows handover --workflow=ship --flush --worktree=` carries the book (handover, deferred-sweep, ledger rows) into a throwaway `origin/dev` checkout → **one** `chore({FID}): ship FAILED bkit [skip ci]` commit, **one** push to `dev` (`dev` moved → rebuilt, pushed again; refused → record stays in `BOOK_ROOT` for the next ship of `{FID}`). It never touches the open PR's validated head, so the open-PR guard does not apply, and the handover survives the branch prune. Comment posted only when `handoverNeeded`, linked only where the flush pushed.
725
747
 
726
- `/bkit-design` = only command without conditional handover (no max-retry loop).
748
+ `/bkit-design` and `/bkit-plan` run no handover subagent (no max-retry loop); they still keep the record.
727
749
 
728
750
  ### Rebase Conflict Tiering
729
751
 
@@ -826,7 +848,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
826
848
  | 9 — Design Organise | `@bkit-design-organise` | `design-v2-reviewed.md` | `design-v3-organised.md` (versioned draft) | Decompose design into dependency-annotated workstreams (`WS-N`). `ORGANISE_VERDICT` = FAIL (cycles) → Failure Path. |
827
849
  | 10 — Summary | `@bkit-design-summary` | highest design-v* + glob design-* | `design-summary.md` | Commit `chore({FID}): summary bkit [skip ci]` → push. `SUMMARY_VERDICT` = FAIL → Failure Path. Glob picks up `design-spike.md` — `Feasibility` leads with a spike FAIL. |
828
850
  | 11 — Suggest Workstreams | — | `design-v3-organised.md` | parent-issue comment, `status.jsonl` | `bkit workstreams comment` reads `## Suggested Workstreams` (none parsed → exit 3 → Failure Path) and builds one advisory comment for the parent issue: one line per `WS-N` (`Requires` included), the `**Parent design:**` line each workstream issue carries, plus the design link. `NEVER auto-trigger`. Never creates an issue, never comments on another issue, never sets blockers. |
829
- | 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`. Local (runtime pushes dev, dev lock): checkout `dev` → stray-artifact check → squash `feat/{FID}` → non-doc and canonical-blob checks → roadmap row → `docs({FID}): design DONE` commit (`--squash-of`) → push `dev` → remove the workflow-created worktree and its branch. PR mode: roadmap commit → push → open or reuse the PR → squash-merge it (exit 80 hands either stage to MCP; re-run with `--pr` / `--merged-sha`). Both: landed-body scan, transport cross-check, `close-transport` row, lock release → `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, then the star line) as `## bkit Tips`, then offers a plain-English explanation on request. |
851
+ | 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, `update-branch` 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. |
830
852
 
831
853
  **Hard stop in Step 12 caution block:** "Design requires human review. Do not invoke `/bkit-plan`."
832
854
 
@@ -850,7 +872,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
850
872
  | 9 — Check `Complexity` | `@bkit-plan-complexity-check` | `COMPLEXITY_VERDICT` ∈ {SINGLE, SPLIT}, read and recorded on the `plan-complexity-check` row as `verdict` by `steps finish --agent=bkit-plan-complexity-check` (the agent's own verdict set); exit 5 / 6 re-asks the agent. |
851
873
  | 10 — Split Plan | `@bkit-plan-complexity-split` _(only if `split`)_ | Writes `{FID}-plan-N.md` sub-plans + `plan-split.md` log; self-verifies losslessness (`SPLIT_VERDICT` ∈ {PASS, FAIL}; FAIL → Failure Path). |
852
874
  | 11 — Summary | `@bkit-plan-summary` | Commit `chore({FID}): summary bkit [skip ci]` → push. |
853
- | 12 — Close Workflow | — | Archive any existing canonical → copy v4 → sync to `dev`, remove worktree, delete branches (same as `/bkit-design` Step 12, except `workflows promote` moves the whole `{FID}-plan*.md` set to the archive under one timestamp, copies the split's children as `{FID}-plan-{k}.md` with working names rewritten, and stamps `designPath` / `designBaseSha` into the anchor). Set state `In Review`; phase label `Plan` persists. Final return displays `plan-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, then the star line) as `## bkit Tips`, then offers a plain-English explanation on request. |
875
+ | 12 — Close Workflow | — | Archive any existing canonical → copy v4 → sync to `dev`, remove worktree, delete branches (same as `/bkit-design` Step 12, except `workflows promote` moves the whole `{FID}-plan*.md` set to the archive under one timestamp, copies the split's children as `{FID}-plan-{k}.md` with working names rewritten, and stamps `designPath` / `designBaseSha` into the anchor). Set state `In Review`; phase label `Plan` persists. Final return displays `plan-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, the star line, then how to silence both) as `## bkit Tips`, then offers a plain-English explanation on request. |
854
876
 
855
877
  **Hard stop in Step 12 caution block:** "Plan requires human review. Do not invoke `/bkit-build`."
856
878
 
@@ -882,7 +904,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
882
904
  | 15 — Diagnose Failure | `@bkit-debug-failure-diagnose` _(only if Step 14 FAIL)_ | Reads the committed Step 14 test log `docs/plans/{YYYYMM}/logs/{FID}/run-tests-{TEST_ATTEMPT}.md`. Writes `build-failure-diagnose-{TEST_ATTEMPT}.md`. |
883
905
  | 16 — Remediate Failure | `@bkit-debug-failure-remediate` _(only if Step 14 FAIL)_ | 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 14 (its next row is the next `TEST_ATTEMPT`). > `MAX_TEST_ATTEMPT` → Failure Path. |
884
906
  | 17 — Summary | `@bkit-build-summary` | 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 18). `bkit-cloud.yml` backstop: no-op while build runs (`.bkit/cloud.md` § Branch-aware routing). |
885
- | 18 — Close Workflow & Create PR | — | `bkit:auto` re-read before close-workflow commit; open-PR probe; if any changed path sits under a `migrations/` or `migrate/` directory (case-insensitive, any depth — covers Supabase, Prisma, Drizzle, Rails) and HEAD lacks `bkit [force build]` → amend or empty commit with `bkit [force build]` → push. `bkit prs open` (base pinned `dev`; body = the `bkit:issue` / `bkit:fid` marker + plan path; retries the create once; reads the base back → exit 6 when it is not `dev`, guarding repos whose default base is `main`); exit 80 → `create_pull_request` with the printed `title` / `body` / `base` / `head`. Then CI-Dispatch Gate (`bkit runs dispatch`). Set state `In Review`; phase label `Build` persists. Worktree persists for follow-up `/bkit-debug` or `/bkit-ship`. Final return displays `build-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, then the star line) as `## bkit Tips`, then offers a plain-English explanation on request. |
907
+ | 18 — Close Workflow & Create PR | — | `bkit:auto` re-read before close-workflow commit; open-PR probe; if any changed path sits under a `migrations/` or `migrate/` directory (case-insensitive, any depth — covers Supabase, Prisma, Drizzle, Rails) and HEAD lacks `bkit [force build]` → amend or empty commit with `bkit [force build]` → push. `bkit prs open` (base pinned `dev`; body = the `bkit:issue` / `bkit:fid` marker + plan path; retries the create once; reads the base back → exit 6 when it is not `dev`, guarding repos whose default base is `main`); exit 80 → `create_pull_request` with the printed `title` / `body` / `base` / `head`. Then CI-Dispatch Gate (`bkit runs dispatch`). Set state `In Review`; phase label `Build` persists. Worktree persists for follow-up `/bkit-debug` or `/bkit-ship`. Final return displays `build-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, the star line, then how to silence both) as `## bkit Tips`, then offers a plain-English explanation on request. |
886
908
 
887
909
  **Failure Path includes handover** — when triggered by exhausted retry counts, invokes `@bkit-debug-abort-handover` and posts `Workflow Handover` comment.
888
910
 
@@ -903,7 +925,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
903
925
  <!-- prettier-ignore -->
904
926
  | Step | Subagent(s) | Notes |
905
927
  | --- | --- | --- |
906
- | 1 — Start Workflow | — | Pre-flight: `bkit repo info --fetch`. `bkit issues labels --failed=off --debug=on`: adds `bkit:debug` additively (prior phase label persists) and clears `bkit:failed`; state `In Progress`. PR-mode: `PR_NUMBER` → `PUSH_MODE`. `DEBUG_ATTEMPT` + `DEBUG_MODE` per Mode detection above. no commits on `dev` — `start-workflow` step entry deferred to Step 2 inside the worktree. |
928
+ | 1 — Start Workflow | — | Pre-flight: `bkit repo info --fetch`. `bkit issues labels --phase=debug`: sets `bkit:debug`, drops the prior phase label, `next:*` and `bkit:failed`; state `In Progress`. PR-mode: `PR_NUMBER` → `PUSH_MODE`. `DEBUG_ATTEMPT` + `DEBUG_MODE` per Mode detection above. no commits on `dev` — `start-workflow` step entry deferred to Step 2 inside the worktree. |
907
929
  | 2 — Worktree Setup | — | Branch handling differs from feat workflows: debug MINTS NOTHING. Resume `.worktrees/{FID}` → else adopt an already-existing `feat/{FID}` (local or origin) into a worktree → else adopt the session's current branch in place (`WORKTREE_PATH=$REPO_ROOT`, no `git worktree add`, no `-b`), which is also the path taken when the session is already sitting on `feat/{FID}` (git refuses one branch in two worktrees). Branch eligibility: any branch but `main` — else Failure Path. `bkit worktrees setup` (no `--branch`, no `-b`; `main` → exit 7). Writes `debug-input-{DEBUG_ATTEMPT}.md` (failure description only — no workflow state). Persists `debugAttempt` / `debugMode` / `pushMode` (`bkit status meta`; `--soak-entry` when the run starts in SOAK). |
908
930
  | 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`; `[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 + `NORMAL_ATTEMPT` <= `MAX_NORMAL_ATTEMPT` → Step 4; FAIL + NORMAL + exhausted → `bkit status meta --soak-entry --debug-mode=SOAK` (fresh `SOAK_ATTEMPT` budget) → Step 4; FAIL + SOAK + `SOAK_ATTEMPT` < `MAX_SOAK_ATTEMPT` → Step 4; else → Failure Path. |
909
931
  | 4 — Fetch Context | — | _(on FAIL with budget, or before Reproduce)_ Mode-agnostic. Every consumer `context-fetch` block (`bkit context list-blocks` → `run-block`, 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. |
@@ -913,13 +935,13 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
913
935
  | 8 — Failure Remediate Soak | `@bkit-debug-failure-soak` _(only if `DEBUG_MODE` = SOAK)_ | `SOAK_ATTEMPT` = soak rows since `soakEntryAt` + 1 (`counters derive --since=soakEntryAt`). 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 `SOAK_ATTEMPT` (`MAX_SOAK_ATTEMPT`, counted from each SOAK entry). |
914
936
  | 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. → Step 10. |
915
937
  | 10 — Summary | `@bkit-debug-summary` | Commit `chore({FID}): summary{VERBOSE_SUFFIX}` → push. `SUMMARY_VERDICT` = PASS/CONCERNS → Step 11; FAIL → Failure Path. |
916
- | 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 (`git diff origin/dev..HEAD`, excluding `docs/plans/`) before the CI-triggering push — diff-scoped, not a tree-wide `git grep`, so the bkit-managed prompt/command files that quote the literal marker never false-trip (the soak agent's own `git grep '[DEBUG-OBSERVE]'` self-check in `bkit-debug-failure-soak.md` is the first layer). Else Failure Path. PR open: strip `bkit [verbose ci]` from PR title. Commit `chore({FID}): close-workflow{VERBOSE_SUFFIX}` → push + (LOCAL, no PR) `chore({FID}): create-pr{VERBOSE_SUFFIX}` (`VERBOSE_SUFFIX = " bkit [verbose ci]"` iff `PUSH_MODE = LOCAL`). 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. The handover path runs via Failure Path. Final return displays `debug-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, then the star line) as `## bkit Tips`, then offers a plain-English explanation on request. |
938
+ | 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 (`git diff origin/dev..HEAD`, excluding `docs/plans/`) before the CI-triggering push — diff-scoped, not a tree-wide `git grep`, so the bkit-managed prompt/command files that quote the literal marker never false-trip (the soak agent's own `git grep '[DEBUG-OBSERVE]'` self-check in `bkit-debug-failure-soak.md` is the first layer). Else Failure Path. PR open: strip `bkit [verbose ci]` from PR title. Commit `chore({FID}): close-workflow{VERBOSE_SUFFIX}` → push + (LOCAL, no PR) `chore({FID}): create-pr{VERBOSE_SUFFIX}` (`VERBOSE_SUFFIX = " bkit [verbose ci]"` iff `PUSH_MODE = LOCAL`). 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. The handover path runs via Failure Path. Final return displays `debug-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, the star line, then how to silence both) as `## bkit Tips`, then offers a plain-English explanation on request. |
917
939
 
918
940
  **Failure Path** includes conditional handover via `@bkit-debug-abort-handover` when max-retry exhausted → `debug-handover.md`. PR-mode `bkit [verbose ci]` **preserved** (not stripped) — investigator wants ongoing verbose CI; § `bkit [verbose ci]` Marker Propagation cleanup invariant.
919
941
 
920
- ### `/bkit-ship` — 15 steps
942
+ ### `/bkit-ship` — 14 steps
921
943
 
922
- **Goal:** verify PR, land docs and bookkeeping on it, merge to `dev`, clean up worktree. Path-scoped staging via `bkit ledgers commit` (frozen allow-list); `BOOK_ROOT` resolves the single tree every status write targets (`RUNTIME_DEVPUSHES=true` → `$REPO_ROOT`; `false` → current working branch tree). `{OUTBOX}` (§ Workflow commands) survives Step 14 `worktree remove`.
944
+ **Goal:** verify PR, land docs and bookkeeping on it, merge to `dev`, clean up worktree. Path-scoped staging via `bkit ledgers commit` (frozen allow-list); `BOOK_ROOT` = `{WORKTREE_PATH}` resolves the single tree every status write targets. `{OUTBOX}` (§ Workflow commands) survives the Step 14 worktree removal.
923
945
 
924
946
  **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 — the Close Workflow step's final return is unreachable once the run enters the Failure Path. All five phase workflows carry it.
925
947
 
@@ -947,17 +969,17 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
947
969
  **Close Workflow records the merge-CI verdict and publishes on every runtime:**
948
970
 
949
971
  - `ship-merge-ci` row (verdict + reason) written before routing red → **Failure Path**; a red merge is recorded, never inferred from a missing close row.
950
- - `RUNTIME_DEVPUSHES=true` → commit on the `dev` checkout, push under the dev lock.
951
- - Else → close commit in a detached worktree off `origin/dev` (`{OUTBOX}/close`, ledgers via `bkit ledgers union`) → push `dev`; refused → `ship-close/{FID}` PR, squash subject `[skip ci]`; a PR GitHub refuses to merge stays open for a human.
972
+ - 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.
973
+ - Feature worktree + `{SHIP_BRANCH}` removed only once the close is on `dev` (the book lives there until then).
952
974
  - `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.
953
975
 
954
- **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 15 step keys, pre-merge pushes confined to B2 + Commit + Push Bookkeeping, `.dev.lock`/trap/EXIT, `.deferred-blocked` writer under `BOOK_ROOT`). **Tier-3 carrier:** detector corpus (Sub-plan 3).
976
+ **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 B2 + Commit + Push Bookkeeping, no hand-written `dev` checkout or push, `.deferred-blocked` writer under `BOOK_ROOT`). **Tier-3 carrier:** detector corpus (Sub-plan 3).
955
977
 
956
978
  <!-- prettier-ignore -->
957
979
  | Step | Subagent(s) | Notes |
958
980
  | --- | --- | --- |
959
- | 1 — Start Workflow | — | Resolve `FID`; `bkit runtime detect` → `RUNTIME_*`; resolve `BOOK_ROOT` (RUNTIME_DEVPUSHES conditional); `bkit locks acquire` (`--dev-pushes` when true; missing month bucket → current UTC month); create `{OUTBOX}`; preflight `actions: write` once; `bkit workflows start` opens the run here (its log lives under `BOOK_ROOT`, not the worktree); set label `Ship`, `In Progress`. `ship-input-{RUN}.md` includes the plan when there is one. no commits on `dev`. |
960
- | 2 — Verify PR (Worktree Setup + Regression Guard) | — | `bkit worktrees setup --workflow=ship [--branch=]` resolves `SHIP_BRANCH` (see Branch eligibility), creates / resumes (no rebase) / adopts, and writes the `.worktree-owned` marker to the outbox only for a worktree it created. `bkit runtime row`. `bkit prs probe --head={SHIP_BRANCH} --state=all` → `PR_NUMBER`, `ENTRY_HEAD`, mergeable state. No PR and branch ahead of `origin/dev` → push, `bkit prs open` into `dev` (`workflow-meta` `openedPr:true`), wait for its CI; nothing ahead → Failure Path `Nothing to ship`. Already MERGED → `ship-merged-on-entry` → Step 13. Regression guard: `bkit runs wait --pr= --until=present` (no CI run for PR HEAD → FAIL), then `--until=completed`. |
981
+ | 1 — Start Workflow | — | Resolve `FID`; `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=]` resolves `SHIP_BRANCH` (see Branch eligibility), creates / resumes (no rebase) / adopts, and writes the `.worktree-owned` marker to the outbox only for a worktree it created; in the worktree `bkit status path` → `BOOK_ROOT`, `bkit workflows start` 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`. |
982
+ | 2 — Verify PR (Worktree Setup + Regression Guard) | — | `ship-input-{RUN}.md` in the worktree (includes the plan when there is one). `bkit prs probe --head={SHIP_BRANCH} --state=all` → `PR_NUMBER`, `ENTRY_HEAD`, mergeable state. No PR and branch ahead of `origin/dev` → push, `bkit prs open` into `dev` (`workflow-meta` `openedPr:true`), wait for its CI; nothing ahead → Failure Path `Nothing to ship`. Already MERGED → `ship-merged-on-entry` → Step 13. Regression guard: `bkit runs wait --pr= --until=present` (no CI run for PR HEAD → FAIL), then `--until=completed`. |
961
983
  | 3 — Base Check | — | `bkit branches sync --head=<ENTRY_HEAD>` → `basePath`: A (`origin/dev` is an ancestor) → Step 5; B → Step 4. |
962
984
  | 4 — Integrate (Path B only) | `@bkit-ship-conflict-resolve` _(B2 only)_ | B1 mergeable: `bkit prs update-branch` → Step 5. B2 conflicting: worktree + `@bkit-ship-conflict-resolve` + `bkit ledgers commit --scope=full --mode=stage --stage-tracked-updates` + `bkit branches push --mode=feature` (`--force-with-lease`) → Step 5. Non-mechanical: handover. |
963
985
  | 5 — Deferred Sweep | `@bkit-ship-deferred-sweep` | Fast-forward the worktree to `origin/{SHIP_BRANCH}` (diverged → Failure Path). No `{FID}-plan*.md` → warning + `workflow-meta` `planSource:"brief"`. `@bkit-ship-deferred-sweep`: PASS → Step 6; FAIL touches `$BOOK_ROOT/.../logs/{FID}/.deferred-blocked` → Failure Path (merge never happens). First pass only — gate-refusal re-entry lands at Step 9. |
@@ -968,15 +990,14 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
968
990
  | 10 — Merge Gate + Merge PR | — | `bkit runs gate --pr= --validated=<VALIDATED_HEAD> --branch= --file= --snapshot={OUTBOX}/pre-merge-snapshot.jsonl --record={STATUS}` — the ONLY merge precondition: the snapshot (PR head, `VALIDATED_HEAD`, dev SHA, ancestor, capstone run, mergeable) is written before it decides, a skip token in the PR title refuses (18), a refusal is recorded as `ship-gate-refusal`. `bkit prs merge --match-head=<gate mergeHead> --delete-branch {LABEL_FLAGS} --expect-merged` (empty body). `state` = MERGED → Step 13. Non-zero gate: 10/11/14/17 → bounded Step 9 (poll only); else Failure Path. Non-merged: `bkit counters route --limit=MAX_MERGE_ATTEMPT` → Step 11 or Failure Path. |
969
991
  | 11 — Failure Diagnose | `@bkit-debug-failure-diagnose` _(only if not merged)_ | Writes `ship-failure-diagnose-{MERGE_ATTEMPT}.md`. |
970
992
  | 12 — Failure Remediate | `@bkit-debug-failure-remediate` _(only if not merged)_ | Writes `ship-failure-remediate-{MERGE_ATTEMPT}-log.md`. `Strategy` ladder (`STANDARD → PIVOT → FINAL`). PASS → Step 10 (re-merge). FAIL → Failure Path: its handover sends code-level failures back to build, since a source-file retry loop would re-merge identical remote content. |
971
- | 13 — Switch to Dev | — | `bkit branches switch --dev-pushes= --worktrees=`: under the dev lock, `git checkout dev`, fetch + fast-forward, rebase-and-push local `dev` commits that are all skip-CI (any CI-running local commit → exit 82, needs a human), install dependencies (failure → exit 16 → **Failure Path**). `RUNTIME_DEVPUSHES=false`: skipped (merge already landed server-side). |
972
- | 14 — Worktree Cleanup | — | `bkit worktrees remove --branch={SHIP_BRANCH}` removes only a worktree a workflow created (`.worktree-owned` marker in the outbox; absent = "not mine"), prunes, then deletes the local and remote branch and prunes tracking refs. A worktree still holding the branch (an unmarked one) blocks both deletes and is named in `branchBlockedBy` — a local delete would fail while the remote delete went through. `dev` / `main` refused (exit 2). |
973
- | 15 — 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, and makes the single path-scoped `[skip ci]` close commit under the dev lock: with `--dev-pushes` → `dev` checkout + push `dev`; else a close worktree off `origin/dev` → push `dev`, refused → `ship-close/{FID}` PR; the workflow lock is released before the push. Add `bkit:merged` label, drop `bkit:failed`. Final return displays `ship-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, then the star line) as `## bkit Tips`, then offers a plain-English explanation on request. **HARD STOP**. |
993
+ | 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`. |
994
+ | 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) and releases the lock — 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); step returns to `REPO_ROOT`. Gate 14 reads `status.jsonl` from `origin/dev`. Add `bkit:merged` label, drop `bkit:failed`. `ship-summary.md` is copied to `{OUTBOX}` before the close (the close removes the worktree holding it); final return displays that copy 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**. |
974
995
 
975
- **Failure Path** resolves `BOOK_ROOT` (not `--git-common-dir`), runs `bkit workflows fail` (aborts a rebase, appends `workflow-failed`, releases the lock, clears `.deferred-blocked`), and includes conditional handover via `@bkit-debug-abort-handover` writing `ship-handover.md` when max-retry exhausted.
996
+ **Failure Path** books in `BOOK_ROOT` (not `--git-common-dir`), runs `bkit workflows fail` (aborts a rebase, appends `workflow-failed`, releases the lock, clears `.deferred-blocked`), and includes conditional handover via `@bkit-debug-abort-handover` writing `ship-handover.md` when max-retry exhausted.
976
997
 
977
998
  ### Audits
978
999
 
979
- No command and no phase label. A template in `docs/templates/bkit-audit-*.md` is the procedure (sections, steps, gates). `@bkit-audit-generate` runs one template and writes `docs/audits/{YYYYMM}/{slug}.md`. **If** that month already has this slug → `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Writes only the report and the template's consumer-owned `Project Instructions` below `bkit:end`, refined each run. Final return appends what `bkit tips --workflow=audit` prints (one tip, no star line) as `## bkit Tips`, then offers a plain-English explanation on request. `/bkit-plan` reads a design doc, one or more of those reports, or both.
1000
+ No command and no phase label. A template in `docs/templates/bkit-audit-*.md` is the procedure (sections, steps, gates). `@bkit-audit-generate` runs one template and writes `docs/audits/{YYYYMM}/{slug}.md`. **If** that month already has this slug → `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Writes only the report and the template's consumer-owned `Project Instructions` below `bkit:end`, refined each run. Issue named in the input + tracker wired → posts the final summary there as one `--kind=audit` comment (`### Audit Summary: {slug}`), `STOPPED` runs included; never gates. Final return appends what `bkit tips --workflow=audit` prints (one tip, then how to silence it; no star line) as `## bkit Tips`, then offers a plain-English explanation on request. `/bkit-plan` reads a design doc, one or more of those reports, or both.
980
1001
 
981
1002
  ### `/bkit-auto` — phase-routed dispatch
982
1003
 
@@ -1044,7 +1065,7 @@ Pluggable via `bkit install --tracker=<github|linear|none>`. Per-tracker MCP end
1044
1065
 
1045
1066
  ### Phase labels (mutually exclusive)
1046
1067
 
1047
- Phase labels carry `bkit:` namespace — no consumer clash. Mutual exclusion in workflow code: drop prior phase label from `{LABELS}` before adding new.
1068
+ Phase labels carry `bkit:` namespace — no consumer clash. Mutual exclusion in workflow code: drop prior phase label from `{LABELS}` before adding new. A phase start also drops every `next:*` label (next best workflow for an issue no workflow has started) and `bkit:failed` (a new run supersedes the failed one).
1048
1069
 
1049
1070
  <!-- prettier-ignore -->
1050
1071
  | Label | Meaning |
@@ -1052,10 +1073,11 @@ Phase labels carry `bkit:` namespace — no consumer clash. Mutual exclusion in
1052
1073
  | `bkit:design` | `/bkit-design` running |
1053
1074
  | `bkit:plan` | `/bkit-plan` running |
1054
1075
  | `bkit:build` | `/bkit-build` running |
1076
+ | `bkit:debug` | `/bkit-debug` running |
1055
1077
  | `bkit:ship` | `/bkit-ship` running |
1056
1078
  | `bkit:merged` | `/bkit-ship` completed; PR merged to `dev`; issue left **In Review** (open) — a human reviews post-merge and closes manually (bkit never auto-closes) |
1057
1079
 
1058
- Phase label preserved through Close — tracker state (Linear "In Review", GitHub `open`) carries completion signal; label tells reviewers which workflow finished. Ship exception: Close swaps `bkit:ship` → `bkit:merged`.
1080
+ Phase label preserved through Close — tracker state (Linear "In Review", GitHub `open`) carries completion signal; label tells reviewers which workflow finished and names the next best one (`bkit:design` → plan, `bkit:plan` → build, `bkit:build` / `bkit:debug` → ship; with `bkit:failed` → debug). Ship exception: Close swaps `bkit:ship` → `bkit:merged`.
1059
1081
 
1060
1082
  ### Additive labels (do not drop phase)
1061
1083
 
@@ -1063,8 +1085,7 @@ Phase label preserved through Close — tracker state (Linear "In Review", GitHu
1063
1085
  | Label | Added by | When |
1064
1086
  | --- | --- | --- |
1065
1087
  | `bkit:auto` | Human (via tracker UI) at issue creation | Opt-in gate for `/bkit-auto` CI-mode (ship/debug) dispatch. Removed by any workflow that finds `bkit:auto` absent on the linked issue (kill-switch propagation). |
1066
- | `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 when `/bkit-debug` Step 1 starts (debug entry supersedes the prior failure marker) and when `/bkit-ship` Step 15 adds `bkit:merged` (terminal success; `--phase=merged` implies `--failed=off`). |
1067
- | `bkit:debug` | `/bkit-debug` Step 1 | `/bkit-debug` is running on top of a prior phase (typically `bkit:build` or `bkit:ship`). Prior phase label persists alongside, so reviewers see which workflow is being debugged. |
1088
+ | `bkit:failed` | Failure Path of any workflow | Workflow hit its Failure Path; human triage required. Phase label persists alongside, so reviewers see which workflow failed. Cleared by every phase start (`--phase=*` implies `--failed=off`), including `/bkit-debug` Step 1 and `/bkit-ship` Step 14 `bkit:merged`. |
1068
1089
 
1069
1090
  ### Tracker-specific state
1070
1091
 
@@ -1075,10 +1096,9 @@ Issue state semantics (Linear "In Progress" / "In Review" / "Done"; GitHub `open
1075
1096
  | --- | --- |
1076
1097
  | `issue-update-phase` | Step 1 of every phase. Sets phase label, tracker-specific "active" state. |
1077
1098
  | `issue-update-review` | Close Workflow of `/bkit-design`, `/bkit-plan`, `/bkit-build`, `/bkit-debug`. Hand-off state (Linear "In Review"; GitHub no-op — phase label carries signal). |
1078
- | `issue-update-merged` | `/bkit-ship` Step 15. Ship terminal — drop phase labels, add `bkit:merged`; Linear "In Review", GitHub left **open**. bkit never closes / never sets Done — a human closes on acceptance (merge != acceptance). |
1099
+ | `issue-update-merged` | `/bkit-ship` Step 14. Ship terminal — drop phase labels, add `bkit:merged`; Linear "In Review", GitHub left **open**. bkit never closes / never sets Done — a human closes on acceptance (merge != acceptance). |
1079
1100
  | `issue-update-failed` | Failure Path. Adds `bkit:failed` additive label. |
1080
- | `issue-update-debug` | `/bkit-debug` Step 1. Adds `bkit:debug` additive label and clears `bkit:failed` (`bkit issues labels --failed=off --debug=on`). |
1081
- | `issue-update-status` | Step 1 (design/plan/build/debug/ship) → "In progress"; phase Close (design/plan/build/debug) → "In review"; `/bkit-ship` Step 15 → "In review" (never "Done" — the board mirrors the issue, which stays open for human close). GitHub Projects v2 board (`bkit.githubProject`; skipped if unset/absent). Linear no-op (issue state already carries it). |
1101
+ | `issue-update-status` | Step 1 (design/plan/build/debug/ship) → "In progress"; phase Close (design/plan/build/debug) → "In review"; `/bkit-ship` Step 14 → "In review" (never "Done" — the board mirrors the issue, which stays open for human close). GitHub Projects v2 board (`bkit.githubProject`; skipped if unset/absent). Linear no-op (issue state already carries it). |
1082
1102
 
1083
1103
  ### Comment lifecycle
1084
1104
 
@@ -1149,9 +1169,9 @@ Precedence: `bkit [force build]` on head commit wins.
1149
1169
  | `chore({FID}): summary bkit [skip ci]` (design Step 10 summary, plan Step 11 summary) | `bkit [skip ci]` |
1150
1170
  | `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. |
1151
1171
  | `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. |
1152
- | `docs({FID}): ship DONE` (ship Step 15 close-workflow on `dev`, or its `ship-close/{FID}` PR squash subject) | `bkit [skip ci]` |
1153
- | `docs({FID}): {phase} aborted` (build / debug Failure Path handover) | `bkit [skip ci]` |
1154
- | `chore({FID}): ship FAILED` (ship Failure Path — the single flush; carries the handover and the reconciled branch-side artifacts, so ship emits no `aborted` commit) | `bkit [skip ci]` |
1172
+ | `docs({FID}): ship DONE` (ship Step 14 close-workflow on `dev`, or its `ship-close/{FID}` PR squash subject) | `bkit [skip ci]` |
1173
+ | `docs({FID}): {phase} aborted` (design / plan / build / debug Failure Path record on the feature branch) | `bkit [skip ci]` |
1174
+ | `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]` |
1155
1175
  | `chore({FID}): close-workflow` (build Step 18 — 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 |
1156
1176
  | `chore({FID}): close-workflow` (debug Step 11 PR-mode — opted-in) | none / `bkit [auto route]` (PR-mode, conditional) — same as build |
1157
1177
  | `chore({FID}): create-pr` (debug Step 11 local-mode — opted-in) | none / `bkit [auto route]` (local-mode, conditional) — CI-triggering HEAD in local-mode |
@@ -1169,7 +1189,7 @@ Outcome-verification gate: after final loud push, confirms bkit CI check dispatc
1169
1189
  - **Build Step 18:** close-workflow commit → `bkit branches push --mode=feature --require-ci` (no PR yet, no CI) → `bkit prs open` (the PR creation fires CI) → `bkit runs dispatch --pr=`.
1170
1190
  - **Debug Step 11 PR-mode:** close-workflow push (sub-step 2, `--require-ci`) = CI trigger; gate in sub-step 6.
1171
1191
  - **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.
1172
- - **Ship:** OUT of scope. Step 15 reads the squash commit's CI with `bkit runs gate --head=<SQUASH_SHA>` and records `ship-merge-ci`. CI-Dispatch at ship would mask "essential tests skipped" signal ship backstops.
1192
+ - **Ship:** OUT of scope. Step 14 reads the squash commit's CI with `bkit runs gate --head=<SQUASH_SHA>` and records `ship-merge-ci`. CI-Dispatch at ship would mask "essential tests skipped" signal ship backstops.
1173
1193
  - **Ship Step 9 duplicate-dispatch probe (not the gate):** `bkit runs wait --head=<VALIDATED_HEAD> --branch= --until=present --dispatch-if-absent` probes for a CI-workflow run at that head, presence only (`SHIP_PROBE_ATTEMPTS` x `SHIP_PROBE_INTERVAL_S`), and runs `gh workflow run {bkit.ciWorkflow}` only on no-run. The head move it follows (Path B `bkit prs update-branch`) already fires `pull_request` at the same SHA, 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".
1174
1194
  - **Ship Gate 10 + squash `--body ""`:** merge — squash subject = dev HEAD.
1175
1195
 
@@ -1236,7 +1256,7 @@ Rationale: invariant **contextual** — bkit pushes `[skip ci]` intermediately (
1236
1256
  | `/bkit-build` | 18 (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 |
1237
1257
  | `/bkit-debug` | 10 (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 6 |
1238
1258
  | `/bkit-debug` | 10 (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 |
1239
- | `/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 15 then gates the squash commit with `bkit runs gate --squash-of=<PR>` (not a CI-Dispatch Gate) |
1259
+ | `/bkit-ship` | 10 (merge-pr) | `bkit prs merge` (`gh pr merge --squash --body ""`) — squash subject becomes dev HEAD, body empty | `gh pr merge` is the only API; empty body strips PR-body `bkit [skip ci]` from the squash subject. Step 14 then gates the squash commit with `bkit runs gate --squash-of=<PR>` (not a CI-Dispatch Gate) |
1240
1260
  | `/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. |
1241
1261
  | `/bkit-ship` | 15 (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. |
1242
1262
 
@@ -1249,7 +1269,7 @@ Without `acceptEdits` / wildcard allow surface, every `Bash`, `Edit`, `Write`, M
1249
1269
  <!-- prettier-ignore -->
1250
1270
  | Bucket | Patterns | Purpose |
1251
1271
  | --- | --- | --- |
1252
- | `allow` | `Bash(*)`, `Skill(*)`, `WebSearch`, `mcp__github__*`, `mcp__claude_ai_Linear__*`, `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). |
1272
+ | `allow` | `Bash(*)`, `Skill(*)`, `WebSearch`, `mcp__github__*`, `mcp__claude_ai_Linear__*`, `mcp__linear__*` (the `linear` server in `.mcp.json`), `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). |
1253
1273
  | `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 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 rebase -i:*`, `git rebase \* -i( \*)`, `git rebase \*--interactive\*`, `git \* --no-verify( \*)`, `git commit -n\*`, `git commit \* -n( \*)`; `Read(./.env)`, `Read(./.env.\*)`, `Read(./\*\*/.env)`, `Read(./\*\*/.env.\*)`, `Read(./.bkit/.env)` | Per-call human confirmation for destructive ops, hook-skipping commits / pushes and secret reads. The `\*` globs catch the same git commands with flags in another order (`git reset -q --hard`, `git clean -df`); a git global option before the subcommand (`git -C dir reset --hard`) is not matched. The `.env` rows are globs, not an enumeration of known filenames — 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. |
1254
1274
  | `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. |
1255
1275
 
@@ -1259,7 +1279,7 @@ Shell `curl` / `wget` are **not** on the Claude `ask` list — they run under `B
1259
1279
 
1260
1280
  ### Cloud sessions — what actually applies
1261
1281
 
1262
- `permissions.allow` **grants** capability — applied only after the workspace trust dialog, never shown in a cloud (`-p` / SDK) session. Untrusted → every `allow` row above ignored, sole notice one stderr line no cloud session surfaces; `deny` / `ask` still apply. `bkit install` writes `projects[<repo path>].hasTrustDialogAccepted` into `~/.claude.json` from the generated setup script (`.claude/bkit-cloud.md` § 4) — root, pre-clone, pre-Claude, snapshotted. `.claude/hooks/bkit-cloud-bootstrap.sh` re-checks the discovered repo root each session and warns on mismatch.
1282
+ `permissions.allow` **grants** capability — applied only after the workspace trust dialog, never shown in a cloud (`-p` / SDK) session. Untrusted → every `allow` row above ignored, sole notice one stderr line no cloud session surfaces; `deny` / `ask` still apply. `bkit install` writes `projects[<repo path>].hasTrustDialogAccepted` into `~/.claude.json` from the generated setup script (`.claude/bkit-cloud.md` § Setup script) — root, pre-clone, pre-Claude, snapshotted. `.claude/hooks/bkit-cloud-bootstrap.sh` re-checks the discovered repo root each session and warns on mismatch.
1263
1283
 
1264
1284
  Auto mode **drops** broad allow rules granting arbitrary code execution — blanket `Bash(*)`, wildcarded interpreters, package-manager run commands, `Agent` / `Monitor` rules; narrow rows (`Bash(npm test)`) survive. `Bash(*)` is a non-auto-mode mechanism only; auto mode runs on classifier verdicts + `autoMode.environment`. Classifier reads `autoMode` from user / managed settings **only** — never `.claude/settings.json` / `.claude/settings.local.json`, so the setup script seeds it host-side.
1265
1285
 
@@ -1283,16 +1303,16 @@ Inline definitions for workflow-file tokens. Keep synced with workflow bodies.
1283
1303
 
1284
1304
  Mechanical step work runs as `bkit <noun> <verb> --flag=value` (also `--flag value`); `bkit help` lists the nouns, `bkit <noun> --help` / `bkit <noun> <verb> --help` list verbs, flags, output keys, exit codes. Source `.bkit/core/engine/commands/{workflow,ci,setup}/`, listed in `commands/registry.ts`; conventions enforced by `.bkit/core/engine/commands/conventions.test.ts`.
1285
1305
 
1286
- | Contract | Rule |
1287
- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1288
- | stdout | one JSON object; keys camelCase, matching `status.jsonl` (`parentSha`, `subPlan`). |
1289
- | stderr | Human log lines, tagged `[bkit-<noun>]`. |
1290
- | Flags | kebab-case; same name for the same thing everywhere: `--workflow --step --fid --month --sub-plan --attempt --verdict --artifact` (repeatable). |
1291
- | Exit `0` / `1` / `2` | ok / the answer is no (gate failed, max attempts, lock held) / usage error or missing dependency. |
1292
- | Exit `3`-`79` | Command-specific; listed in that verb's `--help`. |
1293
- | Exit `80` / `81` / `82` | Do it via MCP (`runtimeGithubCli=false`) / hand the wait back to the agent turn loop / needs a human. |
1294
- | Month | `YYYYMM` in UTC. |
1295
- | `status.jsonl` | design / plan / build / debug: `.worktrees/{FID}/` copy when present, else main checkout. ship: main checkout when `RUNTIME_DEVPUSHES=true`, else current worktree top. |
1306
+ | Contract | Rule |
1307
+ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
1308
+ | stdout | one JSON object; keys camelCase, matching `status.jsonl` (`parentSha`, `subPlan`). |
1309
+ | stderr | Human log lines, tagged `[bkit-<noun>]`. |
1310
+ | Flags | kebab-case; same name for the same thing everywhere: `--workflow --step --fid --month --sub-plan --attempt --verdict --artifact` (repeatable). |
1311
+ | Exit `0` / `1` / `2` | ok / the answer is no (gate failed, max attempts, lock held) / usage error or missing dependency. |
1312
+ | Exit `3`-`79` | Command-specific; listed in that verb's `--help`. |
1313
+ | Exit `80` / `81` / `82` | Do it via MCP (`runtimeGithubCli=false`) / hand the wait back to the agent turn loop / needs a human. |
1314
+ | Month | `YYYYMM` in UTC. |
1315
+ | `status.jsonl` | design / plan / build / debug: `.worktrees/{FID}/` copy when present, else main checkout. ship: current worktree top (`{WORKTREE_PATH}`). |
1296
1316
 
1297
1317
  **Invocation:** Step 1's first block runs `repo info` through the lookup expression
1298
1318
 
@@ -1314,20 +1334,20 @@ and holds its `bkit` key as `{BKIT}` (plus `repoRoot` as `{REPO_ROOT}`, `outboxR
1314
1334
  | `repo` | `info`, `preflight` | Step 1 owner/repo, branch, behind-`dev` notice, outdated-bkit advisory, `{BKIT}` / `{REPO_ROOT}` / `{OUTBOX_ROOT}`; advisory dispatch-permission preflight |
1315
1335
  | `fids` | `check`, `parse`, `find` | FID format asserts; marker / branch FID recovery; the feature already logged for an issue (`find --issue`: exit 0 one, 1 none, 4 several) |
1316
1336
  | `runtime` | `detect`, `row`, `assert` | runtime capability table + `runtime-resolved` row |
1317
- | `locks` | `acquire`, `release` | per-feature `.lock` and `.bkit/.dev.lock` |
1337
+ | `locks` | `acquire`, `release` | per-feature `.lock` |
1318
1338
  | `workflows` | `start`, `fail`, `handover`, `close`, `promote`, `links` | `workflow-started`; the Failure Path (`fail`: row, rebase abort, lock, sentinels, labels, failure comment; `handover --push` / ship's `--flush`); `close` (compliance grade, `workflow-done`, telemetry, report, artifact links, `--outbox`, `--message` commit; ship's `--flush` lands on dev); design / plan canonical promotion (`promote`) and close links (`links`) |
1319
1339
  | `worktrees` | `setup`, `remove` | Step 2 worktree create / resume / adopt (`--detect` asks the runtime), copy, install; teardown |
1320
- | `branches` | `sync`, `push`, `land`, `rebase`, `switch`, `anchor-stamp`, `anchor-read` | docs-from-dev merge, base check, every push, design / plan close landing (local squash under the dev lock, or PR squash-merge; audit; lock release), Tier-2 rebase resolve, ship switch-to-dev, anchor block |
1340
+ | `branches` | `sync`, `push`, `land`, `rebase`, `sync-dev`, `anchor-stamp`, `anchor-read` | docs-from-dev merge, base check, every push, design / plan close landing (squash in a throwaway `origin/dev` worktree pushed as `dev` with backoff retries, else PR squash-merge; audit; local `dev` fast-forward; lock release), Tier-2 rebase resolve, ship's local `dev` fast-forward, anchor block |
1321
1341
  | `prs` | `open`, `probe`, `merge`, `update-branch`, `checks`, `verbose-ci`, `scan-body`, `cross-check`, `transport-row` | PR create / lookup, squash merge (empty body, `--match-head`, auto-route suffix from `--label`), server-side base refresh, check-rollup classification (green when present and none failed/pending), debug's verbose-CI title, close-transport audit (`transport-row --scan --cross-check`) |
1322
1342
  | `issues` | `text`, `labels`, `comment` | `ISSUE_TEXT` join + cut, label arithmetic + board payload, comment bodies (MCP posts them) |
1323
1343
  | `runs` | `wait`, `dispatch`, `gate`, `revalidate`, `context`, `mirror`, `declared` | CI polls, CI-Dispatch Gate (`--file` / `--step` record its row, `--label` the re-trigger suffix), ship merge gate (`--pr` / `--squash-of` heads, `--snapshot`, `--record`), ship Step 9 re-validate, auto Step 1 context, release-PR mirror, CI-workflow presence |
1324
1344
  | `tests` | `run`, `red`, `green` | deepest-declared `bkit:gate:*` run + saved log + verdict; build test-first: a task's red via `bkit:test:file` (row + test snapshot), a sub-plan's audit report (§ Test-first) |
1325
1345
  | `status` | `path`, `fold`, `route`, `meta`, `row` | status location, fold, routing state (`route --expect=field=value`), `workflow-meta` rows, typed audit rows the fold skips |
1326
1346
  | `counters` | `derive`, `rows`, `run`, `route`, `max` | attempt counters (step rows or typed audit rows), run number, `MAX_*` routing (`route --of=<step>:<pos>` derives the value; `--of=<step>,<step>:count` sums several steps) |
1327
- | `steps` | `done`, `finish`, `verdict`, `gate`, `stub` | `step-done` row + commit; the one-call step ending (§ Step endings); verdict header read; mechanical gate items (placeholders, FID, lock, artifacts, the row's `attempt` / `strategy` / `scope`); seeding a versioned artifact with a PENDING header |
1347
+ | `steps` | `done`, `finish`, `verdict`, `gate`, `stub` | `step-done` row + commit; the one-call step ending (§ Step endings); verdict header read; mechanical gate items (placeholders, FID, lock, artifacts, the row's `attempt` / `strategy` / `scope`; `--ref` reads `status.jsonl` as committed on a ref); seeding a versioned artifact with a PENDING header |
1328
1348
  | `ledgers` | `commit`, `union`, `only-bookkeeping` | path-scoped bookkeeping staging, ledger union, carry-forward check |
1329
1349
  | `context` | `clamp`, `clamp-log`, `ledger-scan`, `list-blocks`, `run-block`, `finalise` | artifact clamping, plan ledger scan, debug `context-fetch`, `bkit-cloud-bootstrap.sh` provision recipes (`list-blocks` → `provision`) |
1330
- | `roadmap` | `fold`, `feature`, `mirror` | `docs/roadmap.md` re-render; append a phase's `kind:"feature"` row then re-render (`--strict`: exit 1 when it did not land); build / debug close: the row in the worktree, then on dev under the dev lock |
1350
+ | `roadmap` | `fold`, `feature`, `mirror` | `docs/roadmap.md` re-render; append a phase's `kind:"feature"` row then re-render (`--strict`: exit 1 when it did not land); build / debug close: the row in the worktree, then on dev through the throwaway landing |
1331
1351
  | `workstreams` | `parse`, `comment` | design Step 11 advisory comment |
1332
1352
  | `skills` | `prune` | ship Step 7 skill prune |
1333
1353
  | `ci` | `slop`, `prose`, `skip-token` | `slop:delta` gate (CI and `.husky/pre-push`; takes the base sha as `--base=` or its one bare argument), `lint:prose` gate (Vale over `--glob=` files), `.husky/pre-push` skip-CI token check |
@@ -1368,17 +1388,17 @@ No phase needs a plan file. A missing plan is flagged, never fatal; only "nothin
1368
1388
  `bkit issues labels` does the label arithmetic and prints the full set; the tracker MCP call writes it (the command never touches the tracker). Pass each current label as `--label=`.
1369
1389
 
1370
1390
  ```text
1371
- # Phase label (mutually exclusive — drops every other phase label, keeps additive and foreign ones):
1372
- bkit issues labels --phase=<design|plan|build|ship|merged> --label=… → `labels` → `issue-update-phase` tracker snippet
1391
+ # Phase label (mutually exclusive — drops every other phase label, every next:* and bkit:failed; keeps bkit:auto and foreign ones):
1392
+ bkit issues labels --phase=<design|plan|build|debug|ship|merged> --label=… → `labels` → `issue-update-phase` tracker snippet
1373
1393
 
1374
1394
  # Additive label (phase label persists alongside):
1375
- bkit issues labels --failed=on|off --debug=on|off --label=… → `labels` → `issue-update-failed` / `issue-update-debug` tracker snippet
1395
+ bkit issues labels --failed=on|off --label=… → `labels` → `issue-update-failed` tracker snippet
1376
1396
 
1377
1397
  # Auto-route marker (no transition flag needed):
1378
1398
  bkit issues labels --label=… → `autoRouteSuffix` → `AUTO_ROUTE_SUFFIX` in the fence that commits or dispatches
1379
1399
  ```
1380
1400
 
1381
- Phase labels (`bkit:design`/`bkit:plan`/`bkit:build`/`bkit:ship`/`bkit:merged`) are mutually exclusive — drop old before adding new. Additive labels (`bkit:failed`, `bkit:debug`) skip the drop and live alongside the phase label; `bkit:debug` is never a phase. `bkit:failed` is additionally cleared by `/bkit-debug` Step 1 (`--failed=off --debug=on`) and `/bkit-ship` Step 15 (`--phase=merged`, which refuses `--failed=on`) so a successfully-recovered or shipped issue does not carry a stale Failure Path marker. `--board=progress|review` adds the Projects v2 payloads and `linearState`.
1401
+ Phase labels (`bkit:design`/`bkit:plan`/`bkit:build`/`bkit:debug`/`bkit:ship`/`bkit:merged`) are mutually exclusive — drop old before adding new. `--phase` also drops every `next:*` label and `bkit:failed` (refuses `--failed=on`), so a started issue carries no stale next-step hint or Failure Path marker. `bkit:failed` skips the drop on its own and lives alongside the phase label. `--board=progress|review` adds the Projects v2 payloads and `linearState`.
1382
1402
 
1383
1403
  ### Sub-plan loop discovery
1384
1404
 
@@ -1484,7 +1504,7 @@ Allow-list, never deny-list: deny-list on main checkout = `git add -A` by anothe
1484
1504
  | Plan completed | `docs/plans/{YYYYMM}/{FID}-plan*.md` (moved here in `/bkit-ship` Step 9) |
1485
1505
  | Superseded design / plan | `docs/plans/{YYYYMM}/archive/{TIMESTAMP}-{FID}-design.md`, `…-{FID}-plan*.md` (moved here by design / plan close on re-run; reachable by no workflow glob) |
1486
1506
  | Workflow logs | `docs/plans/{YYYYMM}/logs/{FID}/*.md` |
1487
- | Workflow state | `docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` (on `feat/{FID}` for `design`/`plan`/`build`/`debug` + `ship` Steps 1-8, reaching `dev` via squash-merge; `cloud` writes none — stateless dispatcher; see § status.jsonl) |
1507
+ | Workflow state | `docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` (on `feat/{FID}` for `design`/`plan`/`build`/`debug` + every `ship` step, reaching `dev` via squash-merge or ship's close commit; `cloud` writes none — stateless dispatcher; see § status.jsonl) |
1488
1508
  | Concurrency lock | `$REPO_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock` (absolute, main repo working tree) |
1489
1509
  | Per-phase input | `docs/plans/{YYYYMM}/logs/{FID}/{phase}-input.md` (or `debug-input-{DEBUG_ATTEMPT}.md`) |
1490
1510
  | Per-attempt logs | `docs/plans/{YYYYMM}/logs/{FID}/{phase}-{step}-{N}-*.md` (verify, remediate, diagnose loops) |
@@ -1541,7 +1561,7 @@ Orchestrator behavior:
1541
1561
  - **Found-bug:** never silently drop discovered bug → append `kind:"failure"` to `docs/failures.jsonl` immediately.
1542
1562
  - **Path idiom (all JSONL ledgers):** resolve once per bash block:
1543
1563
  - `REPO_ROOT=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")` — main checkout (locks, `.bkit/version`, remotes).
1544
- - `WT=$(git rev-parse --show-toplevel)` — current write tree (worktree while on `feat/{FID}`; main after `cd "$REPO_ROOT"` / switch-to-dev). When the block only uses `git -C "$REPO_ROOT"`, set `WT="$REPO_ROOT"` (same tree).
1564
+ - `WT=$(git rev-parse --show-toplevel)` — current write tree (worktree while on `feat/{FID}`; main after `cd "$REPO_ROOT"`). When the block only uses `git -C "$REPO_ROOT"`, set `WT="$REPO_ROOT"` (same tree).
1545
1565
  - `STATUS="$WT/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl"`
1546
1566
  - `STATS="$WT/.bkit/stats.jsonl"` · `FRICTION="$WT/.bkit/friction.jsonl"`
1547
1567
  - `docs/{deferrals,failures,knowledge,decisions}.jsonl` → `"$WT/docs/…"`. never mix `$REPO_ROOT` and `show-toplevel` for the same ledger in one block.
@@ -1550,7 +1570,7 @@ Orchestrator behavior:
1550
1570
  - **Ledger sweep (every path-scoped staging site):** the `{FID}`/`{YYYYMM}` log-dir entry names one feature and one month bucket — a `status.jsonl` under any other bucket, and any ledger added after the list was written, would be appended to, never staged, and lost at the next `git worktree remove --force` / branch switch / clean. `bkit ledgers commit` therefore carries `docs/plans/*/logs/*/*.jsonl docs/*.jsonl .bkit/*.jsonl` (plus `docs/roadmap.md`) in its own pathspec set alongside the log-dir entry, and passes the whole set to `git ls-files` — git expands the globs itself, so an unmatched glob is empty output (exit 0), never a zsh abort and never shell word-splitting. Sweep root = `--root=` (`$REPO_ROOT` pre-worktree, `$WT` at close, `$BOOK_ROOT` in ship Step 1 / **Failure Path**, cwd in ship B2). Bounded to those three globs on purpose — a repo's own `*.jsonl` data or fixtures must never ride into a `[skip ci]` bookkeeping commit. The `-A` ban stays. Ship's worktree→`BOOK_ROOT` reconciliation (`bkit ledgers union`) unions the same swept set row-wise (append-only NDJSON, never copy over; never `.bkit/issues.jsonl`).
1551
1571
  - **Best-effort:** telemetry never gates workflow. `bkit workflows close` logs a failed stats append and continues (`telemetryWritten` false); the remaining inline appends (feature rows, ship audit rows) keep `… || echo "[bkit-roadmap] append failed: $FILE"`.
1552
1572
  - **Tracker comment:** the close comment carries `bkit workflows close`'s `report` lines (this run vs `med·5` — median of prior 5 same-workflow runs) and `artifactLinks`; telemetry is written once, by `close`, never re-appended after push. `> 5000` rows in `stats.jsonl` → `[bkit-telemetry] WARNING: MAX_ROWS_BEFORE_ROLLUP (5000) exceeded`.
1553
- - **Compliance:** `bkit workflows close` grades the run itself (`gradeCompliance`, fail-open) before it writes the report and before its commit, so the close report carries this run's grade and the `kind:"compliance"` rows land in the close commit; `close` prints `compliance` (the violation count, null when the grader was unavailable). No workflow calls `bkit comply`.
1573
+ - **Compliance:** `bkit workflows close` grades the run itself (`gradeCompliance`, fail-open) before it writes the report and before its commit, so the close report carries this run's grade and the `kind:"compliance"` rows land in the close commit; `close` prints `compliance` (the violation count, null when the grader was unavailable). Ship's close grades from the parent of `--squash-sha`: the whole feature, not its last commit only. No workflow calls `bkit comply`.
1554
1574
  - **STRAY allow-list (design/plan squash):** `^docs/plans/|^docs/roadmap\.md$|^docs/[^/]+\.jsonl$|^\.bkit/[^/]+\.jsonl$` — must admit everything the ledger sweep can stage. `docs/roadmap.md` needs its own alternative: it is the one staged path that is not a `.jsonl`.
1555
1575
  - **Pre-worktree allow-list:** `bkit ledgers commit --scope=core` — `docs/plans/{YYYYMM}/logs/{FID}/`, `.bkit/friction.jsonl`, `.bkit/stats.jsonl`, plus the ledger sweep.
1556
1576