@cbartens/bkit 5.3.0 → 5.5.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 (186) hide show
  1. package/.bkit/README.md +20 -7
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +14 -9
  4. package/.bkit/core/.bkit/README.md +19 -6
  5. package/.bkit/core/.bkit/cloud.md +77 -46
  6. package/.bkit/core/.bkit/comparison.md +3 -3
  7. package/.bkit/core/.bkit/install.md +21 -18
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +6 -3
  10. package/.bkit/core/.bkit/prompts.md +14 -10
  11. package/.bkit/core/.bkit/providers.md +7 -7
  12. package/.bkit/core/.bkit/templates.md +46 -10
  13. package/.bkit/core/.bkit/trackers.md +92 -38
  14. package/.bkit/core/.bkit/workflows.md +140 -116
  15. package/.bkit/core/AGENTS.md +2 -2
  16. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  17. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +2 -2
  23. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  25. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  26. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  28. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  30. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  31. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  33. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  35. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  36. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  38. package/.bkit/core/docs/templates/bkit-audit-issues.md +25 -8
  39. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  40. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  41. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  43. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  44. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  46. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  47. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  48. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  50. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  51. package/.bkit/core/engine/checks/after/auth.ts +88 -45
  52. package/.bkit/core/engine/checks/after/github.ts +18 -5
  53. package/.bkit/core/engine/checks/after/index.ts +1 -1
  54. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  55. package/.bkit/core/engine/checks/before/env.ts +28 -18
  56. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  57. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  58. package/.bkit/core/engine/checks/tips/catalogue.ts +31 -2
  59. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  60. package/.bkit/core/engine/cli.ts +27 -18
  61. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  62. package/.bkit/core/engine/commands/comply.ts +25 -16
  63. package/.bkit/core/engine/commands/install/install.ts +11 -4
  64. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  65. package/.bkit/core/engine/commands/land.ts +156 -0
  66. package/.bkit/core/engine/commands/lib.ts +10 -8
  67. package/.bkit/core/engine/commands/registry.ts +2 -0
  68. package/.bkit/core/engine/commands/tips.ts +7 -3
  69. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  70. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  71. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  72. package/.bkit/core/engine/commands/workflow/issues.ts +106 -42
  73. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  74. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  75. package/.bkit/core/engine/commands/workflow/prs.ts +14 -3
  76. package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
  77. package/.bkit/core/engine/commands/workflow/roadmap.ts +53 -54
  78. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  79. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  80. package/.bkit/core/engine/commands/workflow/steps.ts +26 -17
  81. package/.bkit/core/engine/commands/workflow/workflows.ts +442 -269
  82. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  83. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  84. package/.bkit/core/engine/install/manifest.ts +31 -10
  85. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  86. package/.bkit/core/engine/install/modules/core.ts +97 -4
  87. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  88. package/.bkit/core/engine/install/placeholders.ts +13 -17
  89. package/.bkit/core/engine/install/write.ts +37 -1
  90. package/.bkit/core/engine/render/trackers.ts +35 -23
  91. package/.bkit/core/engine/shared/egress.ts +6 -0
  92. package/.bkit/core/engine/shared/settings.ts +96 -1
  93. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  94. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  95. package/.bkit/core/prompts/bkit-audit-generate.md +80 -7
  96. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  97. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  98. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  99. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  100. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  101. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  102. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  103. package/.bkit/core/prompts/bkit-design-generate.md +2 -1
  104. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  105. package/.bkit/core/prompts/bkit-utility-update-decisions.md +4 -2
  106. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +4 -2
  107. package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
  108. package/.bkit/core/prompts/bkit-utility-update-failures.md +4 -2
  109. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +4 -2
  110. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +12 -5
  111. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  112. package/.bkit/core/workflows/bkit-auto.md +19 -6
  113. package/.bkit/core/workflows/bkit-build.md +64 -22
  114. package/.bkit/core/workflows/bkit-debug.md +72 -28
  115. package/.bkit/core/workflows/bkit-design.md +101 -37
  116. package/.bkit/core/workflows/bkit-plan.md +82 -31
  117. package/.bkit/core/workflows/bkit-ship.md +127 -108
  118. package/.bkit/shared/.bkit/.env.example +8 -0
  119. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  120. package/.bkit/shared/.claude/settings.json +4 -1
  121. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  122. package/.bkit/shared/.cursor/mcp.json +11 -4
  123. package/.bkit/shared/.mcp.json +11 -4
  124. package/.bkit/shared/.opencode/opencode.json +2 -0
  125. package/.bkit/shared/docs/deployments.md +44 -29
  126. package/.bkit/shared/docs/security.md +1 -1
  127. package/.bkit/shared/docs/testing.md +3 -3
  128. package/.bkit/shared/gitignore +1 -2
  129. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  130. package/.bkit/templates/.github/renovate.json5 +1 -1
  131. package/.bkit/templates/.github/workflows/bkit-ci.yml +29 -56
  132. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  133. package/.bkit/templates/.husky/pre-commit +10 -4
  134. package/.bkit/templates/.husky/pre-push +69 -12
  135. package/.bkit/templates/.lintstagedrc.json +5 -1
  136. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
  137. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
  138. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  139. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  140. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  141. package/CHANGELOG.md +85 -1
  142. package/README.md +102 -100
  143. package/dist/checks/after/auth.js +81 -45
  144. package/dist/checks/after/github.js +17 -5
  145. package/dist/checks/after/index.js +1 -1
  146. package/dist/checks/after/tools.js +1 -1
  147. package/dist/checks/before/env.js +24 -17
  148. package/dist/checks/before/mcp.js +4 -2
  149. package/dist/checks/status-holes.js +0 -1
  150. package/dist/checks/tips/catalogue.js +28 -2
  151. package/dist/checks/tips/index.js +44 -28
  152. package/dist/cli.js +27 -19
  153. package/dist/commands/ci/ci.js +100 -0
  154. package/dist/commands/comply.js +20 -13
  155. package/dist/commands/install/install.js +10 -4
  156. package/dist/commands/install/uninstall.js +42 -0
  157. package/dist/commands/land.js +129 -0
  158. package/dist/commands/lib.js +9 -6
  159. package/dist/commands/registry.js +2 -0
  160. package/dist/commands/tips.js +7 -3
  161. package/dist/commands/workflow/branches.js +300 -243
  162. package/dist/commands/workflow/disk.js +452 -0
  163. package/dist/commands/workflow/fids.js +22 -15
  164. package/dist/commands/workflow/issues.js +90 -41
  165. package/dist/commands/workflow/ledgers.js +26 -11
  166. package/dist/commands/workflow/locks.js +35 -130
  167. package/dist/commands/workflow/prs.js +8 -3
  168. package/dist/commands/workflow/repo.js +5 -0
  169. package/dist/commands/workflow/roadmap.js +52 -57
  170. package/dist/commands/workflow/runtime.js +3 -2
  171. package/dist/commands/workflow/status.js +32 -12
  172. package/dist/commands/workflow/steps.js +20 -13
  173. package/dist/commands/workflow/workflows.js +397 -251
  174. package/dist/commands/workflow/workstreams.js +3 -2
  175. package/dist/commands/workflow/worktrees.js +11 -1
  176. package/dist/install/manifest.js +30 -10
  177. package/dist/install/modules/cloud.js +3 -1
  178. package/dist/install/modules/core.js +95 -5
  179. package/dist/install/modules/opencode.js +6 -0
  180. package/dist/install/placeholders.js +13 -19
  181. package/dist/install/write.js +26 -2
  182. package/dist/render/trackers.js +34 -20
  183. package/dist/shared/egress.js +6 -0
  184. package/dist/shared/settings.js +44 -0
  185. package/dist/shared/timeouts.js +8 -7
  186. package/package.json +11 -2
@@ -12,7 +12,7 @@
12
12
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
13
13
  > - Ships to consumers: describe the current setup only. NEVER an internal identifier (tracker issue number, ledger key, review-finding id) and NEVER project history — decisions belong in `docs/decisions.jsonl`, incidents in `docs/knowledge.jsonl`.
14
14
  > - Subagents are leaves, never invoke other subagents.
15
- > - Subagents never touch the tracker. Tracker MCP tools (GitHub Issues, Linear, etc.) are orchestrator / workflow-layer exclusive.
15
+ > - Subagents never touch the tracker. Tracker MCP tools (GitHub Issues, Linear, Jira) are orchestrator / workflow-layer exclusive.
16
16
  > - When you change a workflow file (`.bkit/core/workflows/bkit-*.md`), mirror change here.
17
17
 
18
18
  ## File Layout
@@ -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
 
@@ -81,9 +81,9 @@ Choose by the state of the work. Procedure stays in the command file and in § P
81
81
 
82
82
  ## Tracker Blocks
83
83
 
84
- `.bkit/core/workflows/bkit-*.md` carry wired tracker variants inline (`github`, `linear`) — full per-tracker behaviour (MCP shapes, labels, states) visible at call site. No substitution from `.bkit/trackers.md`; resolver selects/strips inline blocks. Markers:
84
+ `.bkit/core/workflows/bkit-*.md` carry wired tracker variants inline (`github`, `linear`, `jira`) — full per-tracker behaviour (MCP shapes, labels, states) visible at call site. No substitution from `.bkit/trackers.md`; resolver selects/strips inline blocks. Markers:
85
85
 
86
- **Per-tracker pair.** Every tracker call site: consecutive `github` → `linear` pair (no authored `none` — no-tracker rendering = single generic message):
86
+ **Per-tracker group.** Every tracker call site: consecutive `github` → `linear` → `jira` group (no authored `none` — no-tracker rendering = single generic message):
87
87
 
88
88
  ```text
89
89
  <!-- bkit:tracker github start -->
@@ -92,13 +92,16 @@ mcp__github__… call
92
92
  <!-- bkit:tracker linear start -->
93
93
  mcp__linear__… call
94
94
  <!-- bkit:tracker linear end -->
95
+ <!-- bkit:tracker jira start -->
96
+ mcp__jira__… call
97
+ <!-- bkit:tracker jira end -->
95
98
  ```
96
99
 
97
- At `bkit install`: read `bkit.issueTracker` from consumer manifest → keep matching block, drop other when mirroring to `.claude/commands/bkit-*.md` and `.cursor/commands/bkit-*.md`. Under `none` → whole pair collapses to **`_No tracker connected, skip step._`**. List-number prefix (`3. `) preserved on kept block / stub. Sites needing no-tracker function (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`) add trailing `<!-- bkit:tracker false start/end -->` after pair — used under `none` instead of generic message.
100
+ At `bkit install`: read `bkit.issueTracker` from consumer manifest → keep matching block, drop the others when mirroring to `.claude/commands/bkit-*.md` and `.cursor/commands/bkit-*.md`. Under `none` → whole group collapses to **`_No tracker connected, skip step._`**. List-number prefix (`3. `) preserved on kept block / stub. Sites needing no-tracker function (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`) add trailing `<!-- bkit:tracker false start/end -->` after group — used under `none` instead of generic message.
98
101
 
99
- **Conditional blocks (`bkit:tracker true` / `bkit:tracker false`).** Boolean tracker-presence gates for tracker-agnostic content: `true` kept when wired, **removed entirely under `none`** (shared comment `{BODY}` fences, identical github/linear); `false` kept only under `none`. Removed block consumes leading newline — no blank gap.
102
+ **Conditional blocks (`bkit:tracker true` / `bkit:tracker false`).** Boolean tracker-presence gates for tracker-agnostic content: `true` kept when wired, **removed entirely under `none`** (shared comment `{BODY}` fences, identical for every tracker); `false` kept only under `none`. Removed block consumes leading newline — no blank gap.
100
103
 
101
- `github`/`linear` pair only when call **genuinely differs**. Byte-identical bodies → single `true` block — duplicating identical content as pair is redundant. Enforced by `.bkit/core/engine/render/trackers.test.ts` ("no identical github/linear pair"). `none` difference: pair → `_No tracker connected, skip step._` stub; `true` block removed outright — use `true` only where content can vanish under `none` (inline notes, gate items), not where numbered step needs stub to keep number.
104
+ Per-tracker group only when call **genuinely differs**. Byte-identical bodies → single `true` block — duplicating identical content per tracker is redundant. Enforced by `.bkit/core/engine/render/trackers.test.ts` ("no identical github/linear pair"). `none` difference: group → `_No tracker connected, skip step._` stub; `true` block removed outright — use `true` only where content can vanish under `none` (inline notes, gate items), not where numbered step needs stub to keep number.
102
105
 
103
106
  ```text
104
107
  <!-- bkit:tracker true start -->
@@ -110,7 +113,7 @@ At `bkit install`: read `bkit.issueTracker` from consumer manifest → keep matc
110
113
 
111
114
  Limit = `none` rendering. Bare pair collapses to `_No tracker connected, skip step._` — hoisted prose above survives introducing a step that says "skip" (`{QUERY}` with no search, "new comment" with no comment). Hoist only where trailing `false` block supplies real `none` body (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`); at pair-only sites keep shared text inside both blocks so whole step vanishes. Design/debug issue-scan `{QUERY_NL}` prefix + `— NEW comment, no edit.` suffix stay duplicated. **Exception — plan fetch-context (`/bkit-plan` Step 4):** `{QUERY}` hoisted to plain step — tracker-independent local greps (`related-deferrals.md` / `related-failures.md`) in same step consume it and must run under `none`; hoisted definition not orphaned — do not re-duplicate into tracker pair. `{QUERY_NL}` stays inside the pair (search-only, vanishes under `none`).
112
115
 
113
- Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` after `--tracker=github`) → fresh mirrors. Resolver reports lone `github`/`linear` block or unbalanced `true`/`false` pair as orphan — silent regressions unacceptable. New call site → add `github`/`linear` pair inline (no `trackers.md` edit; `none` block only if step must do something without tracker). `.bkit/trackers.md` = reference-only (marker contract + cross-cutting conventions); not substitution source.
116
+ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` after `--tracker=github`) → fresh mirrors. Resolver reports a block outside a full group or unbalanced `true`/`false` pair as orphan — silent regressions unacceptable. New call site → add `github` / `linear` / `jira` group inline (no `trackers.md` edit; `none` block only if step must do something without tracker). `.bkit/trackers.md` = reference-only (marker contract + cross-cutting conventions); not substitution source.
114
117
 
115
118
  **Rationale rehomed from the workflow files** (stripped there per § Workflow Authoring Rules; kept here):
116
119
 
@@ -119,8 +122,8 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
119
122
  - **`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
123
  - **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
124
  - **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.
125
+ - **Roadmap row per phase close:** each close appends its own `kind:"feature"` row through `appendFeature`, then re-renders the `roadmap-status` block from the ledger. Re-rendering is safe because that block is a 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.
126
+ - **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
127
  - **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
128
  - **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
129
  - **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,51 +133,56 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
130
133
  - **Design / plan close on HARD STOP** — human review required before next phase.
131
134
  - **No archive step in ship:** artifacts at canonical `docs/plans/{YYYYMM}/` from design start — nothing to move at close.
132
135
  - **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.
136
+ - **Runtime capability table:** `bkit runtime detect` classifies the runtime (`LOCAL` / `GITHUB_ACTION` / `CLOUD_CLAUDE` / `CLOUD_CURSOR` / `UNKNOWN`) and emits `runtimeWorktrees` / `runtimeDevPushes` / `runtimeGithubCli` (the `runtime-resolved` row's keys; ship holds `{RUNTIME_WORKTREES}`) plus `runtimeHeadless`, derived from `runtime` and never stored on the row (`bkit runtime assert` re-derives it; design Step 3 holds it as `{RUNTIME_HEADLESS}`). Headless = `GITHUB_ACTION` only: a runner job ends when the agent ends its turn, so no reply reaches it. Every other runtime counts as attended; `BKIT_RUNTIME` overrides. `CLOUD_CURSOR` is detected via a `.bkit/.runtime-cursor` marker written by `.cursor/hooks/bkit-preflight.sh` when `is_background_agent` is true (Cursor exposes that only on stdin JSON to the hook, not as an env var). `RUNTIME_DEVPUSHES` is a conservative 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`.
137
+ - **One landing routine for every dev write:** `pushToDev` (`.bkit/core/engine/commands/land.ts`) builds the commit in a throwaway `.worktrees/_land-{FID}` off fresh `origin/dev`, then `git push origin HEAD:dev`. 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.
138
+ - `bkit branches land`: design / plan close (`merge --squash -X ours {BRANCH}`, `docs({FID}): {phase} DONE bkit [skip ci]`); refused → PR merge.
139
+ - `bkit workflows close --flush`: ship close, book carried in (`docs({FID}): ship DONE bkit [skip ci]`); refused → `ship-close/{FID}` PR.
140
+ - `bkit workflows handover --flush` (ship Failure Path) / `--push` from `dev` / `main` / detached (design / plan / build / debug Failure Path): `chore({FID}): {phase} FAILED bkit [skip ci]`; refused → record stays in the run's tree for the next run of `{FID}`. From a `dev` / `main` / detached checkout only the run's own record is carried (§ Failure Path), then handed back.
141
+ - `bkit roadmap mirror`: build / debug; an attempt that committed nothing never counts as mirrored.
142
+ - `bkit branches land` reads `RUNTIME_DEVPUSHES` from the run's `runtime-resolved` row (no row → fresh detect). It picks the default `{BRANCH}` (`true` → `feat/{FID}`, `false` → the current branch) and gates only what surrounds the landing: stray-artifact check, local `dev` fast-forward, worktree + `feat/{FID}` teardown.
143
+ - **PR-mode design/plan closes 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.
144
+ - **`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
145
  - **`[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
146
  - **Design/plan close never waits for CI:** it creates no PR on the local path, and on the PR path the merge subject carries `bkit [skip ci]` so no run is dispatched. A PR-create-then-wait-then-merge shape (build/debug + ship) is for code, not docs-only closes.
139
147
  - **`--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.
148
+ - **Adopt mode does no `git worktree add`:** `RUNTIME_WORKTREES` takes the same conservative default as `RUNTIME_DEVPUSHES` (`false` for `CLOUD_CLAUDE` / `UNKNOWN`): a push to `dev` cannot be tested without making it, and a wrong guess strands a session. The claude.ai GitHub proxy does not limit which branches a push can update; it rejects only branch deletions and non-branch pushes such as tags (https://code.claude.com/docs/en/cloud-environments § GitHub proxy). `RUNTIME_WORKTREES=false` works in place on whatever branch the session is already on, with `WORKTREE_PATH=$REPO_ROOT`, and refuses outright if that branch is `dev`. `/bkit-debug` is the exception: it adopts in place in every runtime once there is no `feat/{FID}` to take, `dev` included, because a fix has to land on the branch that went red.
149
+ - **Ship never checks out `dev`:** Step 13 `bkit branches sync-dev` fetches and fast-forwards local `dev` without a checkout (`git merge --ff-only` + frozen install only when the main checkout is on `dev` and `dev` moved). Local-only `dev` commits → 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
150
  - **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
- - **`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.
151
+ - **`FID` slug assertions (`bkit-auto` Step 1, `bkit runs context`):** `bkit fids` holds the regexes (`runs context` checks a CI_DEV slug against the `any` allowlist and recovers a PR's FID with the same marker / 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, `^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$` for Jira-prefixed slugs, safe `^[a-z0-9][a-z0-9-]*$` for the no-tracker + branch-derive fallback, tracker-agnostic `^([0-9]+|[a-z][a-z0-9]*-[0-9]+)-[a-z0-9-]+$` for the CI_DEV slug arg, `--tracker=any`). They reject path traversal and shell metacharacters in the untrusted PR-body marker before `{FID}` reaches any filesystem path or downstream dispatch. `bkit fids parse` tries the marker first and falls back to the `feat/{FID}` branch only when the marker is missing or malformed, and the fallback must resolve `{ISSUE_ID}` too — from the `{FID}` slug (github: leading numeric segment; linear / jira: 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
152
  - **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.
145
153
  - **`bkit-auto` CI_DEV mode (`bkit runs context`):** a post-merge `dev` CI failure has no open PR to read, so `bkit-cloud.yml` passes the `{FID}` slug instead of a PR number and `runs context` discriminates on `{ARG}` shape (numeric → PR, else slug). The slug is untrusted at the same level as the PR-body marker — it arrives from a commit-message scope on `dev` and the cloud-side `ARG` guard permits `.` and `/` — so the `any` allowlist is asserted (exit 9) before `{FID}` reaches `docs/plans/{YYYYMM}/logs/{FID}/`, `.worktrees/{FID}`, or the `/bkit-debug {FID} {REF}` dispatch. `prNumber`, `prUrl` and `runId` are printed null rather than filled with a `(merged)` sentinel: the Step 1 comment drops its PR and run links in CI_DEV, and a sentinel would render a broken link. The open check (exit 7) and the CI-run lookup (exit 8) are on the CI path only.
146
154
  - **Auto-route marker derivation is fence-local (build Step 18, debug Step 11, ship Step 10):** every site re-reads the issue's labels through the tracker MCP and hands them as `{LABEL_FLAGS}` to the command that writes the commit — `bkit workflows close --label=` (build / debug close commit), `bkit runs dispatch --label=` (the gate's re-trigger commit), `bkit prs merge --label=` (ship's squash subject) — which appends ` bkit [auto route]` on an exact `bkit:auto` match; no `gh` call. Two dead shapes preceded it and must not return: `${LABELS:-}` (an MCP-derived template value that is never assigned as a shell variable, so it always expanded empty), and a `mktemp` path published via `$GITHUB_ENV` (the runner applies `$GITHUB_ENV` only BETWEEN Action steps, while every agent Bash tool call in a cloud dispatch runs inside the one `claude-code-action` step). The exact label match mirrors the kill switch in `bkit-cloud.yml`, the marker's only consumer, so `bkit:auto-paused` / `no-bkit:auto` cannot arm the route. No tracker (`none`) passes no labels and leaves the subject unchanged. The marker becomes permanent `dev` history; that is inherent to reading `head_commit.message` and is not cleaned up later. Any resulting cross-session `/bkit-debug` dispatch loop is capped by `MAX_DEV_DISPATCH_ATTEMPTS` (a workflow-level env in `bkit-cloud.yml`, held equal to `bkit counters max` by `counters.test.ts`).
147
155
  - **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
156
  - **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
157
  - **Staging routes through `bkit ledgers commit`, never a shell pathspec:** a pathspec rebuilt inline per block with unquoted word-splitting and an `ls docs/plans/*/logs/*/*.jsonl docs/*.jsonl .bkit/*.jsonl` glob 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}`.
158
+ - **Failure Path never calls `bkit runtime assert`:** its non-zero route would loop into itself. `workflows fail` / `handover --push` / `--flush` behave identically in every runtime: record written in the run's tree, then pushed on the feature branch or landed via the throwaway `origin/dev` checkout; refused → stays in the run's tree for the next run of `{FID}`. In a cloud container that tree dies with it, so a refused record is lost.
159
+ - **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
160
  - **`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
161
  - **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
162
  - **`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`.
155
163
  - **One `context-fetch` context list and one marker parser:** `CONTEXT_FETCH_CONTEXTS` and `parseContextFetchStart` in `.bkit/core/engine/checks/before/context-fetch.ts`; the `bkit context` runner and the `bkit check` advisories both read them. The consumer table in `.agents/context.md` must list the same contexts — `.bkit/core/engine/audits/templates/context-fetch-contexts.test.ts` asserts it.
156
164
  - **Header `Placeholders:` line is generic on purpose:** workflow headers list only universally-required examples (`{FID}`, `{YYYYMM}`, plus plan's `{PARENT_FID}` / `{PARENT_YYYYMM}`); the rest of the placeholder inventory is asserted at the step that mints / derives each value. Per-placeholder detail: `{OWNER}` and `{REPO}` derived from `{OWNER_REPO}` at Step 1; `{WORKTREE_PATH}` = absolute path set at worktree setup — mint mode (`RUNTIME_WORKTREES=true`): `.worktrees/{FID}`, adopt mode (`RUNTIME_WORKTREES=false`): `$REPO_ROOT` — required for subagent `Context` cwd; `{YYYYMM}` = canonical month bucket for the FID, held from `bkit locks acquire`'s `month`: the feature's existing bucket, else this UTC month — set once at the feature's first start; a feature with logs in two buckets is refused (exit 7). Plan derives `{PARENT_YYYYMM}` from `{PARENT_FID}`'s bucket. Tracker-wired placeholders (`{ISSUE_ID}` / `{STATE}` / `{LABELS}`) asserted inline in each per-tracker `**Tracker:**` row — empty under `none`.
157
- - **Tracker context filtering (`###### bkit:generated` / `###### bkit:ignore-earlier`):** every comment-post template stamps `###### bkit:generated` as its first body line; `###### bkit:ignore-earlier` is human-placed in a body or comment. Both are h6 headings. Detection of both is WHOLE-line and the heading form only. An inline prose mention of a token is never a marker. Both apply at the point of use, never at the fetch — fetch sites return `COMMENTS` raw; the artifact step writes description + comments to files and `bkit issues text --description-file= --comments-file=` joins them into a named variable (`ISSUE_TEXT`; `RELATED_ISSUE_TEXT` per sweep hit), drops marker-carrying comments, then drops everything above the last cut marker. Point-of-use placement lets both steps share one sentence, keeps the fetch sites from drifting apart, and makes the artifact read the named variable and never the raw fields, so the cut cannot be bypassed downstream. Sweep = issue path with a `RELATED_` prefix (`RELATED_DESCRIPTION` / `RELATED_COMMENTS` / `RELATED_ISSUE_TEXT`); keep identical so a change to one is mechanical in the other. Sweep filter + cut must run per hit and accumulator `RELATED_ISSUES` must never be filtered or cut — a marker belongs to its own issue; cutting the concatenation deletes every issue above it. Detection is marker-only: a template-heading-shape fallback needs lockstep maintenance with every template heading and eats human comments sharing a heading; a dedicated h6 whose text is the token is marker-only detection, not a shape fallback. On GitHub, body and comment text via `mcp__github__issue_read` (`get` / `get_comments`); CLI `gh api` is backup only. Ordering: explicit `sort oldest to newest`, same wording per tracker, on every path into `COMMENTS` — including the AGENTS.md skip branch, which bypasses the fetch and arrives newest-first (`AGENTS.md` § Route Step 1). Sort not reverse: correct whatever the call returned (GitHub `/issues/{n}/comments` oldest-first, Linear `list_comments` `orderBy: "createdAt desc"`). Failure is silent — a newest-first stream inverts the cut into keep-superseded / drop-current and still looks trimmed. Not collapsible to a shared `true` block despite identical sort and filter wording: tool names, params and field names differ. **Emitting a cut marker line is prohibited** (`.agents/rules.md` § Tracker context cut): a whole-line `###### bkit:ignore-earlier` in anything the orchestrator posts or writes arms the next run's cut on bkit's own output, deleting the human context above it. Inline mentions of the token are inert. The generated filter is no backstop here: it drops comments only, never an issue body (which the design blocked-by encode rewrites), and never a sweep hit inside `RELATED_ISSUES`. Guards: `commands/workflow/issues.test.ts` (generated drop before cut, last-marker cut, inline mention inert, oldest-first sort); `.bkit/core/engine/audits/workflows/generated-marker.test.ts` fails on any whole-line cut marker in a workflow, this spec, or `.bkit/core/prompts/*.md`.
165
+ - **Tracker context filtering (`###### bkit:generated` / `###### bkit:ignore-earlier`):** every comment-post template stamps `###### bkit:generated` as its first body line; `###### bkit:ignore-earlier` is human-placed in a body or comment. Both are h6 headings. Detection of both is WHOLE-line and the heading form only. An inline prose mention of a token is never a marker. Both apply at the point of use, never at the fetch — fetch sites return `COMMENTS` raw; the artifact step writes description + comments to files and `bkit issues text --description-file= --comments-file=` joins them into a named variable (`ISSUE_TEXT`; `RELATED_ISSUE_TEXT` per sweep hit), drops marker-carrying comments, then drops everything above the last cut marker. Point-of-use placement lets both steps share one sentence, keeps the fetch sites from drifting apart, and makes the artifact read the named variable and never the raw fields, so the cut cannot be bypassed downstream. Sweep = issue path with a `RELATED_` prefix (`RELATED_DESCRIPTION` / `RELATED_COMMENTS` / `RELATED_ISSUE_TEXT`); keep identical so a change to one is mechanical in the other. Sweep filter + cut must run per hit and accumulator `RELATED_ISSUES` must never be filtered or cut — a marker belongs to its own issue; cutting the concatenation deletes every issue above it. Detection is marker-only: a template-heading-shape fallback needs lockstep maintenance with every template heading and eats human comments sharing a heading; a dedicated h6 whose text is the token is marker-only detection, not a shape fallback. On GitHub, body and comment text via `mcp__github__issue_read` (`get` / `get_comments`); CLI `gh api` is backup only. Ordering: explicit `sort oldest to newest`, same wording per tracker, on every path into `COMMENTS` — including the AGENTS.md skip branch, which bypasses the fetch and arrives newest-first (`AGENTS.md` § Route Step 1). Sort not reverse: correct whatever the call returned (GitHub `/issues/{n}/comments` oldest-first, Linear `list_comments` `orderBy: "createdAt desc"`, Jira `listJiraIssueComments` oldest-first). Failure is silent — a newest-first stream inverts the cut into keep-superseded / drop-current and still looks trimmed. Not collapsible to a shared `true` block despite identical sort and filter wording: tool names, params and field names differ. **Emitting a cut marker line is prohibited** (`.agents/rules.md` § Tracker context cut): a whole-line `###### bkit:ignore-earlier` in anything the orchestrator posts or writes arms the next run's cut on bkit's own output, deleting the human context above it. Inline mentions of the token are inert. The generated filter is no backstop here: it drops comments only, never an issue body (which the design blocked-by encode rewrites), and never a sweep hit inside `RELATED_ISSUES`. Guards: `commands/workflow/issues.test.ts` (generated drop before cut, last-marker cut, inline mention inert, oldest-first sort); `.bkit/core/engine/audits/workflows/generated-marker.test.ts` fails on any whole-line cut marker in a workflow, this spec, or `.bkit/core/prompts/*.md`.
158
166
 
159
167
  **Per-tracker operational notes** (rationale kept here, not in the workflow files per § Workflow Authoring Rules):
160
168
 
161
- - **Related-issues scan** (issue-scan): numbered step at design ideate-entry, plan fetch-context, debug fetch-context; `github`/`linear` pair → under `none` collapses to `_No tracker connected, skip step._` (number preserved). Best-effort: semantic search — fetch 15, drop own issue, keep 10 — one comment fetch per hit; `Search unavailable.` on error; never gates, never auto-expands scope (advisory dedup / conflicting-design / prior-incident). All states: closed issues carry strongest dedup signals. Per hit: `## #{number} — {title} ({state})` + `RELATED_ISSUE_TEXT` (issue-path wording, `RELATED_` prefix), appended to `RELATED_ISSUES`; file written once after last hit; design → `related-issues.md` (generate reads `(if present)`, condenses to `## Related Issues` one-liners or `None`); a design hit whose `bkit issues text` exits non-zero (comments did not parse) is skipped and named under its heading (`Skipped: comments did not parse.`), and the design carries on — related issues are background. Plan: `{QUERY}` in plain sub-step → `related-deferrals.md` / `related-failures.md`; `{QUERY_NL}` in the tracker pair → `related-issues.md`; read by `bkit-plan-review-1/2/3`. Debug → `context-related-${DEBUG_ATTEMPT}.md` (`context-*` glob; excluded from `FETCH_VERDICT`). Plan runs fresh scan (standalone plan coverage). No `fields` parameter — the search returns all fields on every hit and must keep doing so; restricting to a subset trades away the content the sweep exists to surface. Artifact is uncapped by decision (§ Context artifact clamping).
169
+ - **Related-issues scan** (issue-scan): numbered step at design ideate-entry, plan fetch-context, debug fetch-context; tracker group → under `none` collapses to `_No tracker connected, skip step._` (number preserved). Best-effort: github / linear semantic search — fetch 15, drop own issue, keep 10; jira keyword JQL (`{QUERY_KW}`, 2-4 terms, one `text ~` per term, ORed, own issue excluded, 10) — one comment fetch per hit; `Search unavailable.` on error; never gates, never auto-expands scope (advisory dedup / conflicting-design / prior-incident). All states: closed issues carry strongest dedup signals. Per hit: `## #{number} — {title} ({state})` + `RELATED_ISSUE_TEXT` (issue-path wording, `RELATED_` prefix), appended to `RELATED_ISSUES`; file written once after last hit; design → `related-issues.md` (generate reads `(if present)`, condenses to `## Related Issues` one-liners or `None`); a design hit whose `bkit issues text` exits non-zero (comments did not parse) is skipped and named under its heading (`Skipped: comments did not parse.`), and the design carries on — related issues are background. Plan: `{QUERY}` in plain sub-step → `related-deferrals.md` / `related-failures.md`; `{QUERY_NL}` (jira `{QUERY_KW}`) in the tracker group → `related-issues.md`; read by `bkit-plan-review-1/2/3`. Debug → `context-related-${DEBUG_ATTEMPT}.md` (`context-*` glob; excluded from `FETCH_VERDICT`). Plan runs fresh scan (standalone plan coverage). No `fields` parameter on github / linear — the search returns all fields on every hit and must keep doing so; restricting to a subset trades away the content the sweep exists to surface. Artifact is uncapped by decision (§ Context artifact clamping).
162
170
  - **Query shape — two variables, not one.** `{QUERY_NL}` = one natural-language sentence, consumed only by the search call; no `sort` / `order` / `orderBy`, no `in:title,body` qualifier (inert in a semantic query), results kept in rank order through the drop-own-issue and keep-first-10 steps or the ranking is discarded before use. The response carries an order but no score, so a relevance THRESHOLD is not implementable — rank position is the only signal. `{QUERY}` = the 3–6 keyword list, plan-only, consumed ONLY by the ledger awk: that awk splits on whitespace and counts distinct term hits with a `>=2 terms` rule, so feeding it a sentence makes every stopword match every line and degrades the scan to "print everything".
163
171
  - **Ledger scans** (plan only, run under `none`): awk counts query-term hits per line (`>=2` distinct terms, or the sole term when one; case-insensitive substring), sorts by hit count desc then line number desc (append-only ledgers → line order is time order), keeps the top 40 per file and footers the total. `cut -f3-` rejoins fields 3..N with tabs, so a literal tab inside a JSONL line survives intact. Backstopped by the `ledger` clamp profile.
164
- - **Projects v2 board sync** (`issue-update-status`): best-effort, never gates; retry once after 5s on failure. `bkit issues labels --board=progress|review --issue= --owner-repo=` builds the three payloads (`addItem`, `listItems`, `updateItem`) from `bkit.githubProject`; `board` null + `boardSkipped` when opted out or not configured. `update_project_item` needs numeric `item_id`, not node id from `add_project_item` → intervening `projects_list` resolve. Status `value` = single-select option id (e.g. `47fc9ee4`), not name. Linear: no-op (state carries status).
165
- - **Blocked-by edges:** GitHub: `###### bkit:blocked-by start` / `end` pair in issue body. Linear: native `blockedBy` (append-only; unchanged edges = no-op).
166
- - **No tracker-issue creation:** Workflows never create tracker issues. `issue_write` method is `update`. Linear `save_issue` always includes `id`. Step 1 resolves an existing issue reference from the session prompt; no match → log `No issue ID in the session prompt.` and stop (not **Failure Path**). Design Step 11 posts `## Suggested Workstreams` as an advisory comment on the parent issue. A human files any follow-up issues.
167
- - **issue-update-review** (phase-close): **update state only — never change label on close.** GitHub: no-op (phase label until ship `issue-update-merged`). Linear: `save_issue({ id, state: "In Review" })` — no `labels` (partial update would drop `bkit:auto`/`bkit:debug`).
168
- - **issue-update-merged** (ship terminal): bkit **never auto-closes / never sets Done**. Ship drops phase labels, adds `bkit:merged`, **In Review** — Linear `state: "In Review"`, GitHub **open** (board → review, not done). Human reviews merged change and closes manually. Merge != acceptance.
172
+ - **Projects v2 board sync** (`issue-update-status`): best-effort, never gates; retry once after 5s on failure. `bkit issues labels --board=progress|review --issue= --owner-repo=` builds the three payloads (`addItem`, `listItems`, `updateItem`) from `bkit.githubProject`; `board` null + `boardSkipped` when opted out or not configured. `update_project_item` needs numeric `item_id`, not node id from `add_project_item` → intervening `projects_list` resolve. Status `value` = single-select option id (e.g. `47fc9ee4`), not name. Linear / Jira: no-op (state / status carries it).
173
+ - **Blocked-by edges:** GitHub: `###### bkit:blocked-by start` / `end` pair in issue body. Linear: native `blockedBy` (append-only; unchanged edges = no-op). Jira: native `Blocks` link (`inwardIssue` = blocker; repeat = no-op).
174
+ - **No tracker-issue creation:** Workflows never create tracker issues. `issue_write` method is `update`. Linear `save_issue` always includes `id`. Jira: no `createJiraIssue` grant. Step 1 resolves an existing issue reference from the session prompt; no match → log `No issue ID in the session prompt.` and stop (not **Failure Path**). Design Step 11 posts `## Suggested Workstreams` as an advisory comment on the parent issue. A human files any follow-up issues.
175
+ - **issue-update-review** (phase-close): **update state only — never change label on close.** GitHub: no-op (phase label until ship `issue-update-merged`). Linear: `save_issue({ id, state: "{TRACKER_STATE}" })` (`bkit.linear.review`) — no `labels` (partial update would drop `bkit:auto`/`bkit:debug`); a team without that state → `Unapplied`, issue stays started (`.bkit/trackers.md` § linear — notes). Jira: transition to `bkit.jira.review`, no label edit; unreachable → `Unapplied` (`.bkit/trackers.md` § jira — setup and notes).
176
+ - **issue-update-merged** (ship terminal): bkit **never auto-closes / never sets Done**. Ship drops phase labels, adds `bkit:merged`, **In Review** — GitHub **open** (board → review, not done), Linear `bkit.linear.review`, Jira `bkit.jira.review` (never category `done`). Human reviews merged change and closes manually. Merge != acceptance.
169
177
 
170
178
  ## Two-Layer Separation Rules
171
179
 
172
- > **Agents never call tracker MCP tools.** Tracker MCP tools (`mcp__github__issue_*`, `mcp__linear__*_issue`, `*_comment`, `list_issues`, etc.) are exclusive to the workflow layer. Agent that calls a tracker is a protocol violation. Sole exception: `bkit-utility-update-roadmap` holds read-only grants (`list_issues`, `issue_read` / `get_issue`) and never writes.
180
+ > **Agents never call tracker MCP tools.** Tracker MCP tools (`mcp__github__issue_*`, `mcp__linear__*_issue`, `mcp__jira__*`, `*_comment`, `list_issues`, etc.) are exclusive to the workflow layer. Agent that calls a tracker is a protocol violation. Exceptions, both human-invoked utilities: `bkit-utility-update-roadmap` holds read-only grants (`list_issues`, `issue_read` / `get_issue`, `searchJiraIssuesUsingJql` / `getJiraIssue`) and never writes; `bkit-utility-update-tracker` reads and writes issue fields (title, labels, board status, priority, size, milestone, parent, blocked-by) and never creates, closes or comments, never touches `bkit:*` labels.
173
181
 
174
182
  <!-- prettier-ignore -->
175
183
  | Capability | Workflow (`.bkit/core/workflows/`) | Agent (`.bkit/core/prompts/`) |
176
184
  | --- | --- | --- |
177
- | Invoke tracker MCP | ✅ | ❌ (read-only exception: `bkit-utility-update-roadmap`) |
185
+ | Invoke tracker MCP | ✅ | ❌ (exceptions: `bkit-utility-update-roadmap` read-only, `bkit-utility-update-tracker` field writes) |
178
186
  | Read/write `docs/` | ✅ | ✅ |
179
187
  | Read/write source | via subagent delegation | ✅ (gated by tool surface) |
180
188
  | Run `git` | ✅ (`add`, `commit`, `push`, worktree ops) | read-only checks (`status`, `branch`, `log`) only |
@@ -193,7 +201,7 @@ Every phase command (`design`, `plan`, `build`, `debug`, `ship`) shares skeleton
193
201
  3. Execution Protocol caution block (header bullets — see below)
194
202
  4. Failure Path
195
203
  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}`)
204
+ 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
205
  7. Phase-specific steps (subagent invocations, gates, per-step new comment post)
198
206
  8. Summary step (subagent → commit → push → verdict)
199
207
  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 +213,9 @@ Every phase command (`design`, `plan`, `build`, `debug`, `ship`) shares skeleton
205
213
 
206
214
  **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
215
 
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.
216
+ **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
217
 
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.
218
+ **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
219
 
212
220
  ### Execution Protocol — header bullets
213
221
 
@@ -223,16 +231,16 @@ Caution-block bullets of the 6 workflow files, in file order. Every bullet carri
223
231
  | **`Failures`** | all 6 | Any step, tool, command failure, or gate that cannot pass → **Failure Path**. |
224
232
  | **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
233
  | **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. |
234
+ | **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
235
  | **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
236
  | **Resume** | design, plan, build, debug, ship | On start, fold status.jsonl; pick up after last `DONE` step in active `IN_PROGRESS` workflow. |
229
237
  | **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). |
238
+ | **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
239
  | **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
240
  | **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
241
  | **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
242
  | **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). |
243
+ | **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
244
  | **Timeouts** | all 6 | Workflow or subagent run > 3600 seconds → **Failure Path**. |
237
245
  | **Limits** | build, debug, ship | Attempt caps by name from `bkit counters max` / `bkit counters route --limit=`. |
238
246
  | **Modes** | debug | `PUSH_MODE` (`PR|LOCAL`) and `DEBUG_MODE` (`NORMAL|SOAK`), both set at Step 1. |
@@ -245,12 +253,11 @@ Caution-block bullets of the 6 workflow files, in file order. Every bullet carri
245
253
  <!-- prettier-ignore -->
246
254
  | Invariant | Rule |
247
255
  | --- | --- |
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. |
256
+ | **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
257
  | **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`. |
258
+ | **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
259
  | **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. |
260
+ | **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
261
 
255
262
  ### `status.jsonl` — workflow state SoT
256
263
 
@@ -264,8 +271,8 @@ Caution-block bullets of the 6 workflow files, in file order. Every bullet carri
264
271
  | Workflow | Location | Mechanism |
265
272
  | --- | --- | --- |
266
273
  | `build`, `debug` | `feat/{FID}` worktree (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`) | Written + committed on `feat/{FID}` via the per-step commits. 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. |
274
+ | `design`, `plan` | `feat/{FID}` worktree (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`) | Written + committed on the throwaway `feat/{FID}` via the per-step commits — exactly like `build`/`debug`. no mid-lifecycle `dev` push; status + generated docs reach `dev` together via the **Close-Workflow squash-merge** (`docs({FID}): {phase} DONE`). Failure Path appends `workflow-failed` to the retained worktree copy, then `bkit workflows handover --push` commits and pushes the record on the feature branch (open PR → not pushed; no `dev` push); the tracker comment carries the failure signal. |
275
+ | `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
276
  | `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
277
 
271
278
  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 +289,9 @@ Rationale: per-run state on `feat/{FID}` removes dev↔feat divergence at source
282
289
  | `workflow-failed` | `{type, workflow, at}` | Terminal — sets the run's `status` to `FAILED`. |
283
290
  | `runtime-resolved` | `{type, workflow, at, runtime, runtimeWorktrees, runtimeDevPushes, runtimeGithubCli, runtimeGithubCliExit, runtimeGithubCliErr, baseSha}` | Step-2 (Worktree Setup) record of the runtime capability table for this run — the first step `{FID}`/`WORKTREE_PATH` are resolved. Written by `bkit runtime row --file=` (detects, then appends), read back by `bkit runtime assert` (exit 4 no row, 5 an unresolved field). Not folded (unrecognised `type` — ignored, no-op) — later steps re-read `runtimeGithubCli` from this row instead of re-probing `gh`; shell state does not survive a Bash-tool-call boundary, so this row is the durable cross-block record. `baseSha` = `git merge-base origin/dev HEAD` for the design/plan worktree (`--base-sha=`, from `bkit worktrees setup`'s `baseSha`), recorded after Step 2's worktree/rebase arm settles; Close Workflow reads it back to stamp the canonical doc's `bkit:anchor` block (§ Anchor Block) rather than recomputing against a `dev` that has since advanced. Empty for build, debug, ship. |
284
291
  | `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`. |
292
+ | `close-transport` | `{type, shape, sha, scanResult, at}` | Close Workflow's own audit-trail entry. `shape` = which close shape ran — `local` (design/plan squash built off `origin/dev` + direct `dev` push), `pr` (design/plan PR squash-merge after the `dev` push was refused), `push` (build/debug direct push to the feature branch); `sha` = the commit landed on `dev`; `scanResult` = `bkit prs scan-body`'s post-close outcome on the LANDED commit BODY (subject excluded), transport-agnostic. Not folded. Emitted by `bkit prs transport-row --kind=close`. |
286
293
  | `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. |
294
+ | `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
295
  | `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
296
  | `ship-revalidate-dispatch` | `{type, workflow, at, head, probe, reason, dispatched, attempts}` | One Step 9 wait. `head` = `VALIDATED_HEAD`; `probe` = presence-probe outcome (`found`/`none`/`err`); `reason` = `head-move` or `gate-refusal`; `dispatched` = whether `bkit runs wait --dispatch-if-absent` ran `gh workflow run {bkit.ciWorkflow}` after the probe found no run. Written by `bkit status row`, not folded. Counted by `bkit counters rows` since the run's `workflow-started` row to bound gate-refusal re-entry against `MAX_REVALIDATE_ATTEMPT`. |
290
297
 
@@ -297,7 +304,7 @@ Rationale: per-run state on `feat/{FID}` removes dev↔feat divergence at source
297
304
  <!-- prettier-ignore -->
298
305
  | Event | Command |
299
306
  | --- | --- |
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` |
307
+ | `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
308
  | `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
309
  | `workflow-meta` | `bkit status meta` (`--debug-mode` / `--push-mode` / `--debug-attempt` / `--plan-source` / `--soak-entry` / `--opened-pr`) |
303
310
  | `workflow-done` + telemetry | `bkit workflows close` |
@@ -411,13 +418,13 @@ Cross-block routing values re-read from `status.jsonl` with `bkit status route -
411
418
 
412
419
  ### Concurrency lock
413
420
 
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).
421
+ `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
422
 
416
423
  **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
424
 
418
425
  ### Comment Lifecycle
419
426
 
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.
427
+ Every workflow step posts new tracker comment via inline `comment-post-step` block (per-tracker `github` / `linear` / `jira` / `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
428
 
422
429
  **Step 1 (first comment):**
423
430
 
@@ -482,6 +489,19 @@ Stderr: {last 20 lines if shell}
482
489
  {handover.md content verbatim}
483
490
  ```
484
491
 
492
+ **Audit summary (`@bkit-audit-generate`, issue named in its input; § Audits):**
493
+
494
+ ```comment
495
+ ###### bkit:generated
496
+ ### Audit Summary: {slug} - Status: {STATUS} - Findings: CRITICAL {n} · HIGH {n} · MEDIUM {n} · LOW {n}
497
+ Report: [{slug}.md](https://github.com/{OWNER_REPO}/blob/{BRANCH}/docs/audits/{YYYYMM}/{slug}.md)
498
+ {final summary, Stopped through Recommended Next Step}
499
+ ```
500
+
501
+ 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.
502
+
503
+ **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.
504
+
485
505
  ### Tracker Writes Are Best-Effort
486
506
 
487
507
  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.
@@ -694,11 +714,10 @@ Then assert each Update/Create artifact exists, non-empty. Empty → **Failure P
694
714
  | `MAX_MERGE_ATTEMPT` | 3 | `/bkit-ship` PR merge retries |
695
715
  | `MAX_REVALIDATE_ATTEMPT` | 3 | `/bkit-ship` poll-only Step 9 re-entries after a gate refusal (10/11/14/17) |
696
716
  | `MAX_DEV_DISPATCH_ATTEMPTS` | 3 | `bkit-cloud.yml` — distinct failed `dev` CI SHAs per FID that may each dispatch `/bkit-debug` |
697
- | Grill rounds | 10 | `/bkit-design` Step 3 interview cap; literal in the step, not in `THRESHOLDS` |
717
+ | Grill rounds | 10 | `/bkit-design` Step 3 interview cap, draft scenario round included (decision rounds <= 9); literal in the step, not in `THRESHOLDS` |
698
718
  | Step timeout | 3600s | Any workflow or subagent run exceeding this → Failure Path; `/bkit-design` Step 3 time waiting on human answers does not count |
699
719
  | 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 |
720
+ | 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
721
  | Ship CI wait | 1800s / 30s | Step 9 completion poll budget / interval (`SHIP_CI_WAIT_TIMEOUT_S` / `SHIP_POLL_INTERVAL_S`) |
703
722
  | Ship presence probe | 6 x 10s | Step 9 run-at-head probe before any dispatch (`SHIP_PROBE_ATTEMPTS` x `SHIP_PROBE_INTERVAL_S`) |
704
723
  | 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 +730,25 @@ Every command has `## 🤖 Failure Path` before Step 1. Any step / tool / gate f
711
730
 
712
731
  **Standard failure (always):**
713
732
 
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.
733
+ 1. Write the error text to `{OUTBOX_ROOT}/error.md`, then one call: `bkit workflows fail --workflow= --fid= --month= --token={LOCK_TOKEN} [--max-exceeded] {LABEL_FLAGS} --step-number= --step-title= --sub-step= --error-file="{OUTBOX_ROOT}/error.md" [--stderr-file=]` (ship adds `--pr=`). State is changed only with a `--token` (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`), `trackerState`, `handoverNeeded` (`--max-exceeded`, a sentinel existed, or a debug run in `SOAK`), and the `### Workflow Failure` `comment`. No dev push.
715
734
  2. Write the labels through the tracker MCP; post `comment`.
716
735
 
717
736
  **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
737
 
719
738
  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.
739
+
740
+ **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):
741
+
742
+ 4. `bkit workflows handover --workflow= --fid= --month= --push --worktree="{WORKTREE_PATH}"`, run in the run's tree:
743
+ - **Feature branch:** `git add -A` → commit `docs({FID}): {phase} aborted bkit [skip ci]` (handover or not) → push `--mode=abort`. 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`.
744
+ - **`dev` / `main` / detached** (debug adopting `dev` / `main`): nothing staged, committed or pushed from the checkout; half-done code never reaches a shared branch. Only the run's own record is carried into a throwaway `origin/dev` checkout: the `.md` logs it wrote in its log folder, that folder's `.jsonl` lines `HEAD` lacks, and the uncommitted rows of that workflow at or after the run's `workflow-started` in `docs/*.jsonl` / `.bkit/*.jsonl` (not `.bkit/issues.jsonl`; 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.
745
+ - 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
746
 
722
747
  5. **STOP** — no downstream steps.
723
748
 
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.
749
+ **Ship exception:** no separate abort commit, no second push. After the optional handover subagent, `bkit workflows handover --workflow=ship --flush --worktree=` carries the book (handover, deferred-sweep, ledger rows) into a throwaway `origin/dev` checkout → **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
750
 
726
- `/bkit-design` = only command without conditional handover (no max-retry loop).
751
+ `/bkit-design` and `/bkit-plan` run no handover subagent (no max-retry loop); they still keep the record.
727
752
 
728
753
  ### Rebase Conflict Tiering
729
754
 
@@ -817,7 +842,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
817
842
  | --- | --- | --- | --- | --- |
818
843
  | 1 — Start Workflow | — | tracker issue | `.lock`, tracker comment | Fetch `origin/dev`. Resolve `{ISSUE_ID}` from the session prompt (no match → stop; never create), set label `bkit:design`, state `In Progress`. no commits on `dev` — `status.jsonl` init + `start-workflow` step entry deferred to Step 2 inside the worktree. |
819
844
  | 2 — Worktree Setup | — | repo | `.worktrees/{FID}`, `bkit.worktree.copy` files, `design-input-{RUN}.md` | `bkit worktrees setup`: create `feat/{FID}` off a freshly fetched `origin/dev`, resume it, or adopt the current branch in place; dependencies installed (install failure → **Failure Path**). `baseSha` → `runtime-resolved` row (§ Anchor Block). |
820
- | 3 — Grill | — | `design-input-{RUN}.md`, newest earlier-run `design-grill-*.md` | `design-grill-{RUN}.md`, `Grill decisions` section appended to `design-input-{RUN}.md`, tracker comment (`--comment-body`) | Orchestrator interviews the human before any design work. Method adapted from Matt Pocock's `grilling` skill (MIT, https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling). Open decisions mapped as a tree; each round asks the whole frontier (every decision whose prerequisites are settled), numbered, each with a recommended answer worded so "yes" accepts it; plain text, no host question tool. Orchestrator looks up facts; only decisions go to the human. Stops on an empty frontier plus human confirmation, a human stop, or 10 rounds. Agreed answers → `Settled`; unanswered at stop → `Assumed, not confirmed`; "don't know" → `Open`. An earlier run's `Settled` entries stay settled. `grill=false` in the session prompt skips the interview; the artifact then reads `Skipped (grill=false).` `runtimeHeadless` = true (read via `bkit runtime assert`) → no question asked, no turn ended: the tree is walked taking each recommended answer as given, every new answer lands in `Assumed, not confirmed`, and the artifact carries a `Headless run ({RUNTIME})` line. The ideate triplet, generate and both reviewers read the section through `design-input-{RUN}.md`. Waiting time is exempt from the 3600s timeout. A `bkit-cloud.yml` `workflow_dispatch` run is headless. |
845
+ | 3 — Grill | — | `design-input-{RUN}.md`, newest earlier-run `design-grill-*.md` | `design-grill-{RUN}.md`, `Grill decisions` section appended to `design-input-{RUN}.md`, tracker comment (`--comment-body`) | Orchestrator interviews the human before any design work. Method adapted from Matt Pocock's `grilling` skill (MIT, https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling). Open decisions mapped as a tree; each round asks the whole frontier (every decision whose prerequisites are settled), numbered, each with a recommended answer worded so "yes" accepts it; plain text, no host question tool. Orchestrator looks up facts; only decisions go to the human. Decision rounds stop on an empty frontier, a human stop, or 9 rounds. The last round asked is always the draft scenario round, counted in the 10-round cap: the orchestrator drafts the acceptance scenario (`Narrative`, `Success Criteria`, `Key Edge Cases`, `Process Sketch` — the four parts of the design's `Acceptance Scenario`) from the whole context — session prompt, issue description and comments, answers, looked-up facts — shows it in full, and asks one question per part it inferred plus a final accept question; an answer that opens new decisions returns to the decision rounds while rounds remain. Agreed answers → `Settled`; unanswered at stop → `Assumed, not confirmed`; "don't know" → `Open`. The draft lands under `### Draft Acceptance Scenario` behind a `DRAFT only` first line saying whether a human reviewed it; a human stop skips the draft round and records the draft unreviewed. `bkit-design-generate` starts its `Acceptance Scenario` from the draft and records each change as a `Decisions` row, with no further confirmation item: the human reviews the scenario again at the plan's `Acceptance Scenario confirmed` box. The plan reads the design, never the draft. An earlier run's `Settled` entries stay settled and its draft is the starting draft. `grill=false` in the session prompt skips the interview; the artifact then reads `Skipped (grill=false).` `runtimeHeadless` = true (read via `bkit runtime assert`) → no question asked, no turn ended: the tree is walked taking each recommended answer as given, every new answer lands in `Assumed, not confirmed`, the draft scenario is written unreviewed, and the artifact carries a `Headless run ({RUNTIME})` line. The ideate triplet, generate and both reviewers read the section through `design-input-{RUN}.md`. Waiting time is exempt from the 3600s timeout. A `bkit-cloud.yml` `workflow_dispatch` run is headless. |
821
846
  | 4 — Brainstorm & Ideate | `@bkit-design-brainstorm-ideate-1` ‖ `-2` ‖ `-3` (parallel triplet) | `design-input-{RUN}.md` | `design-brainstorm-ideate-1.md`, `-2.md`, `-3.md` | Pragmatic / optimal-tradeoff / risk-premortem lenses; effort-tier diversity (`high`/`medium`/`high`); sibling-blind. `BRAINSTORM_VERDICT` = worst of three. |
822
847
  | 5 — Generate Design | `@bkit-design-generate` | `design-input-{RUN}.md` (carries the `Grill decisions` section), all three brainstorms, `related-issues.md`, superseded `{YYYYMM}/{FID}-design.md` (if any) | `design-v1-draft.md` (versioned draft) | First write of deliverable design doc. Superseded design = context only, never a constraint; supplied HERE only — not to the sibling-blind ideate triplet. |
823
848
  | 6 — Design Review | `@bkit-design-review-1` ‖ `@bkit-design-review-2` (parallel) | `design-v1-draft.md`, `design-input-{RUN}.md` | `design-review-1.md`, `design-review-2.md` (opinion-only logs) | Effort-tier diversity (high vs medium); sibling-blind. `REVIEW_VERDICT` = worst of two. FAIL → Failure Path. `SPIKE` = `Spike` header from `design-review-1.md` only. |
@@ -826,7 +851,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
826
851
  | 9 — Design Organise | `@bkit-design-organise` | `design-v2-reviewed.md` | `design-v3-organised.md` (versioned draft) | Decompose design into dependency-annotated workstreams (`WS-N`). `ORGANISE_VERDICT` = FAIL (cycles) → Failure Path. |
827
852
  | 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
853
  | 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. |
854
+ | 12 — Close Workflow | — | — | `{YYYYMM}/{FID}-design.md` (copy of v3), `{YYYYMM}/archive/` (superseded, re-run only) | `bkit workflows promote` (anchor stamped from the runtime-resolved base commit, any changed canonical archived, v3 copied to the canonical bucket) → `bkit workflows close --record-step --outbox --message=` (compliance grade, close row, telemetry, `chore({FID}): close-workflow` commit in the worktree) → `cd {REPO_ROOT}` → `bkit branches land` (§ Close squash). Direct: stray-artifact check (runtime pushes dev) → squash `{BRANCH}` in `.worktrees/_land-{FID}` off `origin/dev` → non-doc and canonical-blob checks → roadmap row → `docs({FID}): design DONE` commit (`--squash-of`) → `git push origin HEAD:dev`, rebuilt and retried with backoff when `dev` moved. Push refused → PR mode: roadmap commit → push → open or reuse the PR → squash-merge it, `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
855
 
831
856
  **Hard stop in Step 12 caution block:** "Design requires human review. Do not invoke `/bkit-plan`."
832
857
 
@@ -850,7 +875,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
850
875
  | 9 — Check `Complexity` | `@bkit-plan-complexity-check` | `COMPLEXITY_VERDICT` ∈ {SINGLE, SPLIT}, read and recorded on the `plan-complexity-check` row as `verdict` by `steps finish --agent=bkit-plan-complexity-check` (the agent's own verdict set); exit 5 / 6 re-asks the agent. |
851
876
  | 10 — Split Plan | `@bkit-plan-complexity-split` _(only if `split`)_ | Writes `{FID}-plan-N.md` sub-plans + `plan-split.md` log; self-verifies losslessness (`SPLIT_VERDICT` ∈ {PASS, FAIL}; FAIL → Failure Path). |
852
877
  | 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. |
878
+ | 12 — Close Workflow | — | Archive any existing canonical → copy v4 → sync to `dev`, remove worktree, delete branches (same as `/bkit-design` Step 12, except `workflows promote` moves the whole `{FID}-plan*.md` set to the archive under one timestamp, copies the split's children as `{FID}-plan-{k}.md` with working names rewritten, and stamps `designPath` / `designBaseSha` into the anchor). Set state `In Review`; phase label `Plan` persists. Final return displays `plan-summary.md` verbatim, appends what `bkit tips --workflow=<name>` prints (one tip, the star line, then how to silence both) as `## bkit Tips`, then offers a plain-English explanation on request. |
854
879
 
855
880
  **Hard stop in Step 12 caution block:** "Plan requires human review. Do not invoke `/bkit-build`."
856
881
 
@@ -882,7 +907,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
882
907
  | 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
908
  | 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
909
  | 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. |
910
+ | 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
911
 
887
912
  **Failure Path includes handover** — when triggered by exhausted retry counts, invokes `@bkit-debug-abort-handover` and posts `Workflow Handover` comment.
888
913
 
@@ -903,7 +928,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
903
928
  <!-- prettier-ignore -->
904
929
  | Step | Subagent(s) | Notes |
905
930
  | --- | --- | --- |
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. |
931
+ | 1 — Start Workflow | — | Pre-flight: `bkit repo info --fetch`. `bkit issues labels --phase=debug`: sets `bkit:debug`, drops the prior phase label, `next:*` and `bkit:failed`; state `In Progress`. PR-mode: `PR_NUMBER` → `PUSH_MODE`. `DEBUG_ATTEMPT` + `DEBUG_MODE` per Mode detection above. no commits on `dev` — `start-workflow` step entry deferred to Step 2 inside the worktree. |
907
932
  | 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
933
  | 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
934
  | 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 +938,13 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
913
938
  | 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
939
  | 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
940
  | 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. |
941
+ | 11 — Close Workflow | — | A live `prs probe --head` (any base; skipped on `dev` / `main`) sets `{PR_OPEN}` and re-records `PUSH_MODE` (`bkit status meta --push-mode`); labels, the subject suffix, the title strip and `TRIGGER_PR` all key on it, not on the Step-1 value. No-leak assertion: fails the run if any added `[DEBUG-OBSERVE]` line survives the debug diff (`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
942
 
918
943
  **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
944
 
920
- ### `/bkit-ship` — 15 steps
945
+ ### `/bkit-ship` — 14 steps
921
946
 
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`.
947
+ **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
948
 
924
949
  **Summary is displayed verbatim before the Failure Path.** A FAIL summary's `Recommended Next Step` is the only handoff that reaches a human on that route — the Close Workflow step's final return is unreachable once the run enters the Failure Path. All five phase workflows carry it.
925
950
 
@@ -947,17 +972,17 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
947
972
  **Close Workflow records the merge-CI verdict and publishes on every runtime:**
948
973
 
949
974
  - `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.
975
+ - Close commit built in a throwaway `.worktrees/_land-{FID}` off `origin/dev` (book's logs copied, ledgers via `bkit ledgers union`) → push `dev`; `dev` moved → rebuilt, pushed again; refused → `ship-close/{FID}` PR, squash subject `[skip ci]`; a PR GitHub refuses to merge stays open for a human, worktree kept.
976
+ - Feature worktree + `{SHIP_BRANCH}` removed only once the close is on `dev` (the book lives there until then).
952
977
  - `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
978
 
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).
979
+ **Tier-1 carrier:** `bkit runs gate` + `bkit ledgers` + the `TIMEOUTS` table (`commands/workflow/runs.test.ts`, `commands/workflow/ledgers.test.ts`, `.bkit/core/engine/shared/timeouts.test.ts`). **Tier-2 carrier:** `.bkit/core/engine/audits/workflows/ship-invariants.test.ts` (no `git add -A`, `bkit ledgers` staging, `BOOK_ROOT` status writes, `--match-head-commit`, canonical 14 step keys, pre-merge pushes confined to 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
980
 
956
981
  <!-- prettier-ignore -->
957
982
  | Step | Subagent(s) | Notes |
958
983
  | --- | --- | --- |
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`. |
984
+ | 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`. |
985
+ | 2 — Verify PR (Worktree Setup + Regression Guard) | — | `ship-input-{RUN}.md` in the worktree (includes the plan when there is one). `bkit prs probe --head={SHIP_BRANCH} --state=all` → `PR_NUMBER`, `ENTRY_HEAD`, 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
986
  | 3 — Base Check | — | `bkit branches sync --head=<ENTRY_HEAD>` → `basePath`: A (`origin/dev` is an ancestor) → Step 5; B → Step 4. |
962
987
  | 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
988
  | 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 +993,14 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
968
993
  | 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
994
  | 11 — Failure Diagnose | `@bkit-debug-failure-diagnose` _(only if not merged)_ | Writes `ship-failure-diagnose-{MERGE_ATTEMPT}.md`. |
970
995
  | 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**. |
996
+ | 13 — Update Local Dev | — | `bkit branches sync-dev`: fetch + fast-forward local `dev` to `origin/dev`, no checkout (`merge --ff-only` + frozen install when the main checkout is on `dev` and `dev` moved; install failure → exit 16 → **Failure Path**). Local-only `dev` commits → logged with the publish command, never pushed; step still passes. Step key `ship-switch-to-dev`. |
997
+ | 14 — Close Workflow | — | `bkit runs gate --squash-of=<PR> --capstone-only --record={STATUS}` → records `ship-merge-ci`, then refuses unless the capstone passed at the squash commit. The capstone job's result alone decides: the run's conclusion and other jobs (deploys, notifications) never fail the close of a merged PR. `bkit workflows close --flush --pr-number= --squash-sha= --outbox= --token=` grades compliance, records `ship-close-workflow`, writes telemetry in the worktree, lands the single path-scoped `[skip ci]` close commit on `dev` via the throwaway checkout (refused → `ship-close/{FID}` PR) 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
998
 
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.
999
+ **Failure Path** books in `BOOK_ROOT` (not `--git-common-dir`), runs `bkit workflows fail` (aborts a rebase, appends `workflow-failed`, releases the lock, clears `.deferred-blocked`), and includes conditional handover via `@bkit-debug-abort-handover` writing `ship-handover.md` when max-retry exhausted.
976
1000
 
977
1001
  ### Audits
978
1002
 
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.
1003
+ No command and no phase label. A template in `docs/templates/bkit-audit-*.md` is the procedure (sections, steps, gates). `@bkit-audit-generate` runs one template and writes `docs/audits/{YYYYMM}/{slug}.md`. **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. No issue named + tracker wired → read-only search for the template's audit parent (`.bkit/trackers.md` § Issue shapes); found → summary posted there; none open → `Recommended Next Step` suggests one, with the built comment saved to `{OUTBOX_ROOT}/audit-{slug}/parent-comment.md` to post as its first comment. `Suggested Issues` rows are always filed as sub-issues of the parent, existing or new. Final return appends what `bkit tips --workflow=audit` prints (one tip, then how to silence it; no star line) as `## bkit Tips`, then offers a plain-English explanation on request. `/bkit-plan` reads a design doc, one or more of those reports, or both.
980
1004
 
981
1005
  ### `/bkit-auto` — phase-routed dispatch
982
1006
 
@@ -986,7 +1010,7 @@ No command and no phase label. A template in `docs/templates/bkit-audit-*.md` is
986
1010
  | Step | Notes |
987
1011
  | --- | --- |
988
1012
  | 1 — Start Workflow | `bkit repo info --allow-detached` (holds `{BKIT}`, `{OUTBOX_ROOT}`), then one `bkit runs context --phase={PHASE} --arg={ARG}`: classifies `{PHASE}` → `MODE` (CI-status aliases `success`/`pass` → `ship`, `failure`/`fail` → `debug` let the Cursor dashboard paste `/bkit-auto $CI_STATUS $PR_NUMBER` literally; unknown → exit 3). `MODE` = CI: `gh pr view {ARG}` → branch / head / state (open required, exit 7) / URL; the CI run at that head (exit 8 when none); `{FID}` + `{ISSUE_ID}` from the PR-body marker, else the `feat/{FID}` branch (exit 9 when neither parses); `gh` missing → exit 80 → **Failure Path**. `MODE` = CI_DEV: `{ARG}` is the `{FID}` slug itself (allowlist first), `{ISSUE_ID}` = its leading issue segment, `BRANCH` = `dev`, `HEAD_SHA` = `origin/dev`; no PR, no run link. `MODE` = brief: `{ISSUE_ID}` = `{ARG}`. Gate 1 = `bkit steps gate --placeholder=` for the mode's values. The dispatched skill owns FID / `status.jsonl` / worktree. Create fresh tracker comment header. **Stateless — no `status.jsonl`, no `dev` commit.** |
989
- | 2 — Dispatch | Derive `{REF}` — the issue reference in a shape the dispatched workflow's own Step 1 parses (`#N` for GitHub, `ABC-123` for Linear). Route `{PHASE}` → `/bkit-ship {FID} {REF}` / `/bkit-debug {FID} {REF}` / `/bkit-design {REF}` / `/bkit-plan {REF}` / `/bkit-build {REF}`. Invoke via `Skill` (Claude) / `Task` (Cursor); dispatched skill owns its session from there. The regression-gate-verification gate that catches Vercel-ignore / partial-tier demotion lives in `/bkit-ship` Step 2 — Regression Guard (universal — also applies to manual `/bkit-ship` invocations that bypass the workflow). |
1013
+ | 2 — Dispatch | Derive `{REF}` — the issue reference in a shape the dispatched workflow's own Step 1 parses (`#N` for GitHub, `ABC-123` for Linear / Jira). Route `{PHASE}` → `/bkit-ship {FID} {REF}` / `/bkit-debug {FID} {REF}` / `/bkit-design {REF}` / `/bkit-plan {REF}` / `/bkit-build {REF}`. Invoke via `Skill` (Claude) / `Task` (Cursor); dispatched skill owns its session from there. The regression-gate-verification gate that catches Vercel-ignore / partial-tier demotion lives in `/bkit-ship` Step 2 — Regression Guard (universal — also applies to manual `/bkit-ship` invocations that bypass the workflow). |
990
1014
 
991
1015
  **CI-class skip conditions:** one tracker no-op line, exit 0. Only real failures (missing args, tracker unreachable, malformed state) → Failure Path. Loop bound: `/bkit-debug` enforces `MAX_DEBUG_ATTEMPT` = 3 internally; cloud never counts attempts.
992
1016
 
@@ -1040,11 +1064,11 @@ Refused (exit 7): `dev` / `main` as the working branch (debug: `main` only), a d
1040
1064
 
1041
1065
  ## Tracker Integration
1042
1066
 
1043
- Pluggable via `bkit install --tracker=<github|linear|none>`. Per-tracker MCP endpoints, tool names, call shapes inline at each site as `github`/`linear`/`none` blocks; installer keeps chosen, drops others when mirroring `.claude/commands/` + `.cursor/commands/` (§ Tracker Blocks). `.bkit/trackers.md` = marker contract + cross-cutting conventions only.
1067
+ Pluggable via `bkit install --tracker=<github|linear|jira|none>`. Per-tracker MCP endpoints, tool names, call shapes inline at each site as `github` / `linear` / `jira` / `none` blocks; installer keeps chosen, drops others when mirroring `.claude/commands/` + `.cursor/commands/` (§ Tracker Blocks). `.bkit/trackers.md` = marker contract + cross-cutting conventions only.
1044
1068
 
1045
1069
  ### Phase labels (mutually exclusive)
1046
1070
 
1047
- Phase labels carry `bkit:` namespace — no consumer clash. Mutual exclusion in workflow code: drop prior phase label from `{LABELS}` before adding new.
1071
+ 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
1072
 
1049
1073
  <!-- prettier-ignore -->
1050
1074
  | Label | Meaning |
@@ -1052,10 +1076,11 @@ Phase labels carry `bkit:` namespace — no consumer clash. Mutual exclusion in
1052
1076
  | `bkit:design` | `/bkit-design` running |
1053
1077
  | `bkit:plan` | `/bkit-plan` running |
1054
1078
  | `bkit:build` | `/bkit-build` running |
1079
+ | `bkit:debug` | `/bkit-debug` running |
1055
1080
  | `bkit:ship` | `/bkit-ship` running |
1056
1081
  | `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
1082
 
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`.
1083
+ Phase label preserved through Close — tracker state (GitHub `open`, Linear / Jira review state) 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
1084
 
1060
1085
  ### Additive labels (do not drop phase)
1061
1086
 
@@ -1063,22 +1088,20 @@ Phase label preserved through Close — tracker state (Linear "In Review", GitHu
1063
1088
  | Label | Added by | When |
1064
1089
  | --- | --- | --- |
1065
1090
  | `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. |
1091
+ | `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
1092
 
1069
1093
  ### Tracker-specific state
1070
1094
 
1071
- Issue state semantics (Linear "In Progress" / "In Review" / "Done"; GitHub `open`/`closed` + Projects v2) inline as per-tracker blocks:
1095
+ Issue state semantics (GitHub `open`/`closed` + Projects v2; Linear / Jira `progress` / `review` from `bkit.linear` / `bkit.jira`, never done) inline as per-tracker blocks:
1072
1096
 
1073
1097
  <!-- prettier-ignore -->
1074
1098
  | Snippet | When |
1075
1099
  | --- | --- |
1076
1100
  | `issue-update-phase` | Step 1 of every phase. Sets phase label, tracker-specific "active" state. |
1077
- | `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). |
1101
+ | `issue-update-review` | Close Workflow of `/bkit-design`, `/bkit-plan`, `/bkit-build`, `/bkit-debug`. Hand-off state (GitHub no-op — phase label carries signal; Linear / Jira `review`). |
1102
+ | `issue-update-merged` | `/bkit-ship` Step 14. Ship terminal — drop phase labels, add `bkit:merged`; GitHub left **open**, Linear / Jira `review`. bkit never closes / never sets Done — a human closes on acceptance (merge != acceptance). |
1079
1103
  | `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). |
1104
+ | `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 / Jira no-op (issue state already carries it). |
1082
1105
 
1083
1106
  ### Comment lifecycle
1084
1107
 
@@ -1086,7 +1109,7 @@ new comment per workflow step via tracker MCP. Step 1 = first comment; later ste
1086
1109
 
1087
1110
  ### Issue blockers (`/bkit-build` Step 1)
1088
1111
 
1089
- `/bkit-build` Step 1: tracker `issue-read` → parse blocker relations (Linear: `relations.blocked_by` via `get_issue({ includeRelations: true })`; GitHub: `###### bkit:blocked-by start` … `end` block in the body). Blocker not closed/done → Failure Path `Blocked by {BLOCKER_ID} (state: {BLOCKER_STATE})`. Workflows never write those edges. A human sets them.
1112
+ `/bkit-build` Step 1: tracker `issue-read` → parse blocker relations (GitHub: `###### bkit:blocked-by start` … `end` block in the body; Linear: `relations.blocked_by` via `get_issue({ includeRelations: true })`; Jira: JQL `issue in linkedIssues('{ISSUE_ID}', 'is blocked by') AND statusCategory != Done`). Blocker not closed/done → Failure Path `Blocked by {BLOCKER_ID} (state: {BLOCKER_STATE})`. Workflows never write those edges. A human sets them, directly or by running `@bkit-utility-update-tracker`.
1090
1113
 
1091
1114
  ## GitHub Integration
1092
1115
 
@@ -1149,9 +1172,9 @@ Precedence: `bkit [force build]` on head commit wins.
1149
1172
  | `chore({FID}): summary bkit [skip ci]` (design Step 10 summary, plan Step 11 summary) | `bkit [skip ci]` |
1150
1173
  | `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
1174
  | `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]` |
1175
+ | `docs({FID}): ship DONE` (ship Step 14 close-workflow on `dev`, or its `ship-close/{FID}` PR squash subject) | `bkit [skip ci]` |
1176
+ | `docs({FID}): {phase} aborted` (design / plan / build / debug Failure Path record on the feature branch) | `bkit [skip ci]` |
1177
+ | `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
1178
  | `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
1179
  | `chore({FID}): close-workflow` (debug Step 11 PR-mode — opted-in) | none / `bkit [auto route]` (PR-mode, conditional) — same as build |
1157
1180
  | `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 +1192,7 @@ Outcome-verification gate: after final loud push, confirms bkit CI check dispatc
1169
1192
  - **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
1193
  - **Debug Step 11 PR-mode:** close-workflow push (sub-step 2, `--require-ci`) = CI trigger; gate in sub-step 6.
1171
1194
  - **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.
1195
+ - **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
1196
  - **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
1197
  - **Ship Gate 10 + squash `--body ""`:** merge — squash subject = dev HEAD.
1175
1198
 
@@ -1236,7 +1259,7 @@ Rationale: invariant **contextual** — bkit pushes `[skip ci]` intermediately (
1236
1259
  | `/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
1260
  | `/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
1261
  | `/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) |
1262
+ | `/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
1263
  | `/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
1264
  | `/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
1265
 
@@ -1249,8 +1272,8 @@ Without `acceptEdits` / wildcard allow surface, every `Bash`, `Edit`, `Write`, M
1249
1272
  <!-- prettier-ignore -->
1250
1273
  | Bucket | Patterns | Purpose |
1251
1274
  | --- | --- | --- |
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). |
1253
- | `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. |
1275
+ | `allow` | `Bash(*)`, `Skill(*)`, `WebSearch`, `mcp__github__*`, `mcp__linear__*` (the `linear` server in `.mcp.json`), `mcp__jira__*` (the `jira` server), `Bash(git push --force-with-lease:*)`, `Read(./.env.example)`, `Read(./\*\*/.env.example)`, `WebFetch(domain:…)` per host in the network allowlist (apex + `*.` wildcard) | Blanket-allow shell, skills, tracker MCP, scoped web fetch. Claude evaluates `deny`, then `ask`, then `allow`: an `allow` row never overrides a matching `ask` or `deny`. `--force-with-lease` passes because no `deny` row matches it, not because of its `allow` row; the `.env.example` rows never fire, since `Read(./.env.*)` asks first. Session-conditional: bucket needs workspace trust; `Bash(*)` dropped in auto mode (§ Cloud sessions). |
1276
+ | `ask` | `sudo:*`, `brew install:*`, `(pnpm / npm / bun) publish:*`, `gh repo delete:*`, `gh pr close:*`, `gh release delete:*`; git: `git reset --hard:*`, `git reset \*--hard\*`, `git -\* reset \*--hard\*`, `git clean -fd(x):*`, `git clean -\*f\*`, `git filter-branch:*`, `git checkout -- .:*`, `git checkout \*.`, `git checkout \* . \*`, `git restore .:*`, `git restore \*.`, `git restore \* . \*`, `git stash drop:*`, `git stash clear:*`, `git rebase -i:*`, `git rebase \* -i( \*)`, `git rebase \*--interactive\*`, `git \* --no-verify( \*)`, `git commit -n\*`, `git commit \* -n( \*)`; `Read(./.env)`, `Read(./.env.\*)`, `Read(./\*\*/.env)`, `Read(./\*\*/.env.\*)`, `Read(./.bkit/.env)` | Per-call human confirmation for destructive ops, hook-skipping commits / pushes and secret reads. The `\*` globs catch the same git commands with flags in another order (`git reset -q --hard`, `git clean -df`); a git global option before the subcommand (`git -C dir reset --hard`) is not matched. The `.env` rows are globs, not an enumeration of known filenames — 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
1277
  | `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
1278
 
1256
1279
  Shell `curl` / `wget` are **not** on the Claude `ask` list — they run under `Bash(*)`, with `deny`, the auto-mode classifier, and the advisory `.claude/hooks/bkit-guardrails.cjs` (PreToolUse, matcher `Bash`) as the backstops. Claude rules match a command prefix, not a URL host, so per-domain allows are inexpressible and the only options are blanket-ask or blanket-allow; blanket-ask forces a prompt on **every** shell fetch in **every** mode (a content-scoped `ask` is evaluated before the classifier and beats a matching `allow`), which a cloud session has nobody to answer. `WebFetch(domain:…)` governs the `WebFetch` **tool** only, never `curl` in `Bash`. Cursor gates by parsed URL host (`bkit-guardrails.cjs`), OpenCode via `curl https://{host}/*` allows layered after a `curl *` ask (command-string glob: trailing flags or extra URLs still match, so it narrows rather than blocks). All four run an **allowlisted-host** fetch unprompted; on an **undeclared** host Cursor and OpenCode ask, Claude and Codex emit an advisory instead (Claude to avoid re-adding the prompt, Codex because it cannot prompt).
@@ -1259,7 +1282,7 @@ Shell `curl` / `wget` are **not** on the Claude `ask` list — they run under `B
1259
1282
 
1260
1283
  ### Cloud sessions — what actually applies
1261
1284
 
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.
1285
+ `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
1286
 
1264
1287
  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
1288
 
@@ -1271,7 +1294,7 @@ Auto mode **drops** broad allow rules granting arbitrary code execution — blan
1271
1294
  | `deny` | Blocks | Blocks, before the classifier is consulted |
1272
1295
  | Undeclared network host | Reachable once trusted | Classifier-blocked unless named in `autoMode.environment` |
1273
1296
 
1274
- `.mcp.json` declares `mcpServers.linear.url = https://mcp.linear.app/mcp` and `mcpServers.github.url = https://api.githubcopilot.com/mcp/`. SessionStart hook `bash .claude/hooks/bkit-preflight.sh` runs at every session start.
1297
+ `.mcp.json` declares the wired tracker's server: `mcpServers.github.url = https://api.githubcopilot.com/mcp/`, `mcpServers.linear.url = https://mcp.linear.app/mcp` or `mcpServers.jira.url = https://mcp.atlassian.com/v2/mcp`. SessionStart hook `bash .claude/hooks/bkit-preflight.sh` runs at every session start.
1275
1298
 
1276
1299
  **Anti-pattern:** never `--dangerously-skip-permissions` on host. Sandbox CI containers only.
1277
1300
 
@@ -1283,16 +1306,16 @@ Inline definitions for workflow-file tokens. Keep synced with workflow bodies.
1283
1306
 
1284
1307
  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
1308
 
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. |
1309
+ | Contract | Rule |
1310
+ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
1311
+ | stdout | one JSON object; keys camelCase, matching `status.jsonl` (`parentSha`, `subPlan`). |
1312
+ | stderr | Human log lines, tagged `[bkit-<noun>]`. |
1313
+ | Flags | kebab-case; same name for the same thing everywhere: `--workflow --step --fid --month --sub-plan --attempt --verdict --artifact` (repeatable). |
1314
+ | Exit `0` / `1` / `2` | ok / the answer is no (gate failed, max attempts, lock held) / usage error or missing dependency. |
1315
+ | Exit `3`-`79` | Command-specific; listed in that verb's `--help`. |
1316
+ | Exit `80` / `81` / `82` | Do it via MCP (`runtimeGithubCli=false`) / hand the wait back to the agent turn loop / needs a human. |
1317
+ | Month | `YYYYMM` in UTC. |
1318
+ | `status.jsonl` | design / plan / build / debug: `.worktrees/{FID}/` copy when present, else main checkout. ship: current worktree top (`{WORKTREE_PATH}`). |
1296
1319
 
1297
1320
  **Invocation:** Step 1's first block runs `repo info` through the lookup expression
1298
1321
 
@@ -1314,23 +1337,23 @@ and holds its `bkit` key as `{BKIT}` (plus `repoRoot` as `{REPO_ROOT}`, `outboxR
1314
1337
  | `repo` | `info`, `preflight` | Step 1 owner/repo, branch, behind-`dev` notice, outdated-bkit advisory, `{BKIT}` / `{REPO_ROOT}` / `{OUTBOX_ROOT}`; advisory dispatch-permission preflight |
1315
1338
  | `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
1339
  | `runtime` | `detect`, `row`, `assert` | runtime capability table + `runtime-resolved` row |
1317
- | `locks` | `acquire`, `release` | per-feature `.lock` and `.bkit/.dev.lock` |
1340
+ | `locks` | `acquire`, `release` | per-feature `.lock` |
1318
1341
  | `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
1342
  | `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 |
1343
+ | `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
1344
  | `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
1345
  | `issues` | `text`, `labels`, `comment` | `ISSUE_TEXT` join + cut, label arithmetic + board payload, comment bodies (MCP posts them) |
1323
1346
  | `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
1347
  | `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
1348
  | `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
1349
  | `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 |
1350
+ | `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
1351
  | `ledgers` | `commit`, `union`, `only-bookkeeping` | path-scoped bookkeeping staging, ledger union, carry-forward check |
1329
1352
  | `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 |
1353
+ | `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
1354
  | `workstreams` | `parse`, `comment` | design Step 11 advisory comment |
1332
1355
  | `skills` | `prune` | ship Step 7 skill prune |
1333
- | `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 |
1356
+ | `ci` | `slop`, `prose`, `skip-token`, `min-push` | `slop:delta` gate (CI and `.husky/pre-push`; takes the base sha as `--base=` or its one bare argument), `lint:prose` gate (Vale over `--glob=` files), `.husky/pre-push` skip-CI token check, `.husky/pre-push` min-push check (every file the pushed `--ref=`s change matches `bkit.minPushPaths`; exit 0 yes, 1 no, 7 range unreadable) |
1334
1357
  | `setup` | `protect-main` | `main` branch protection requiring `bkit.capstoneJob` |
1335
1358
 
1336
1359
  CI check names come from `package.json` `bkit.capstoneJob` (default `bkit-tests-check`) and `bkit.ciWorkflow` (default `bkit-ci.yml`) — no command hard-codes a check, workflow file, or app folder.
@@ -1344,7 +1367,7 @@ Step 1 of every phase resolves `FID` before taking the lock (the lock path is `l
1344
1367
  1. Session prompt names it — an `FID` slug, a `feat/{FID}` branch, or a `docs/plans/` path carrying it.
1345
1368
  2. Current branch is `feat/{FID}`.
1346
1369
  3. `ISSUE_ID` known → the feature already logged for that issue (`logs/{issue}-*/`, issue lowercased). Two features for one issue → Failure Path listing both; the prompt must name one.
1347
- 4. Mint: `{ISSUE_ID}-{slug}` (Linear id lowercased), slug = title kebab, stopwords stripped, <=3 tokens, ASCII lower. No tracker → `{branch-suffix}-{slug}`.
1370
+ 4. Mint: `{ISSUE_ID}-{slug}` (Linear / Jira key lowercased), slug = title kebab, stopwords stripped, <=3 tokens, ASCII lower. No tracker → `{branch-suffix}-{slug}`.
1348
1371
 
1349
1372
  One FID for all artifacts once set. A workflow never takes `FID` from the newest leftover `.lock` or newest month bucket: on a fresh run with no issue or plan, that silently attached the run to an unrelated feature's logs.
1350
1373
 
@@ -1368,17 +1391,17 @@ No phase needs a plan file. A missing plan is flagged, never fatal; only "nothin
1368
1391
  `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
1392
 
1370
1393
  ```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
1394
+ # Phase label (mutually exclusive — drops every other phase label, every next:* and bkit:failed; keeps bkit:auto and foreign ones):
1395
+ bkit issues labels --phase=<design|plan|build|debug|ship|merged> --label=… → `labels` → `issue-update-phase` tracker snippet
1373
1396
 
1374
1397
  # 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
1398
+ bkit issues labels --failed=on|off --label=… → `labels` → `issue-update-failed` tracker snippet
1376
1399
 
1377
1400
  # Auto-route marker (no transition flag needed):
1378
1401
  bkit issues labels --label=… → `autoRouteSuffix` → `AUTO_ROUTE_SUFFIX` in the fence that commits or dispatches
1379
1402
  ```
1380
1403
 
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`.
1404
+ 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. `trackerState` = the Linear or Jira state the transition moves to: `progress` on a phase start or `--board=progress`, `review` on `bkit:merged`, `bkit:failed` or `--board=review`, named by package.json `bkit.linear` / `bkit.jira` `progress` / `review` (defaults `started` / `In Review` on Linear, `In Progress` / `In Review` on Jira); null under github and none.
1382
1405
 
1383
1406
  ### Sub-plan loop discovery
1384
1407
 
@@ -1399,9 +1422,10 @@ Each gate is the previous gate plus its own tier, so the name and the value desc
1399
1422
  | Gate | Seeded default | Called by |
1400
1423
  | --- | --- | --- |
1401
1424
  | `bkit:gate:format` | `pnpm lint-staged` | `.husky/pre-commit` |
1425
+ | `bkit:gate:min` | `pnpm format:check && pnpm lint:prose && pnpm slop:delta` | `.husky/pre-push` on a min push |
1402
1426
  | `bkit:gate:static` | `pnpm typecheck && pnpm lint && pnpm format:check && pnpm lint:prose && pnpm slop:delta` | `@bkit-build-plan-execute`, `.husky/pre-push` revert path |
1403
- | `bkit:gate:static-unit` | `pnpm bkit:gate:static && pnpm test` | build Steps 7 + 14, `.husky/pre-push`, `@bkit-build-plan-gaps-remediate`, `@bkit-build-challenge-remediate`, `@bkit-build-challenge-tests`, `@bkit-build-plan-verify`, `@bkit-debug-failure-remediate` |
1404
- | `bkit:gate:static-unit-integration` | not seeded — `pnpm bkit:gate:static-unit && pnpm test:integration` | build Steps 7 + 14 |
1427
+ | `bkit:gate:static-unit` | `pnpm bkit:gate:static && pnpm test` | build Steps 7 + 14, `.husky/pre-push` (no integration gate declared), `@bkit-build-plan-gaps-remediate`, `@bkit-build-challenge-remediate`, `@bkit-build-challenge-tests`, `@bkit-build-plan-verify`, `@bkit-debug-failure-remediate` |
1428
+ | `bkit:gate:static-unit-integration` | not seeded — `pnpm bkit:gate:static-unit && pnpm test:integration` | build Steps 7 + 14, `.husky/pre-push` |
1405
1429
  | `bkit:gate:static-unit-integration-e2e` | not seeded — chains the gate above | debug Step 3 |
1406
1430
  | `bkit:gate:static-unit-integration-e2e-live` | not seeded — chains the gate above | debug Step 3 |
1407
1431
  | `bkit:gate:install-static-unit-build` | `pnpm install --frozen-lockfile && pnpm bkit:gate:static-unit && pnpm build` | `@bkit-ship-conflict-resolve` |
@@ -1484,7 +1508,7 @@ Allow-list, never deny-list: deny-list on main checkout = `git add -A` by anothe
1484
1508
  | Plan completed | `docs/plans/{YYYYMM}/{FID}-plan*.md` (moved here in `/bkit-ship` Step 9) |
1485
1509
  | 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
1510
  | 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) |
1511
+ | 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
1512
  | Concurrency lock | `$REPO_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock` (absolute, main repo working tree) |
1489
1513
  | Per-phase input | `docs/plans/{YYYYMM}/logs/{FID}/{phase}-input.md` (or `debug-input-{DEBUG_ATTEMPT}.md`) |
1490
1514
  | Per-attempt logs | `docs/plans/{YYYYMM}/logs/{FID}/{phase}-{step}-{N}-*.md` (verify, remediate, diagnose loops) |
@@ -1541,7 +1565,7 @@ Orchestrator behavior:
1541
1565
  - **Found-bug:** never silently drop discovered bug → append `kind:"failure"` to `docs/failures.jsonl` immediately.
1542
1566
  - **Path idiom (all JSONL ledgers):** resolve once per bash block:
1543
1567
  - `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).
1568
+ - `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
1569
  - `STATUS="$WT/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl"`
1546
1570
  - `STATS="$WT/.bkit/stats.jsonl"` · `FRICTION="$WT/.bkit/friction.jsonl"`
1547
1571
  - `docs/{deferrals,failures,knowledge,decisions}.jsonl` → `"$WT/docs/…"`. never mix `$REPO_ROOT` and `show-toplevel` for the same ledger in one block.
@@ -1550,7 +1574,7 @@ Orchestrator behavior:
1550
1574
  - **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
1575
  - **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
1576
  - **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`.
1577
+ - **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
1578
  - **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
1579
  - **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
1580