@cbartens/bkit 5.3.0 โ†’ 5.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/.bkit/README.md +3 -2
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +8 -2
  4. package/.bkit/core/.bkit/README.md +2 -1
  5. package/.bkit/core/.bkit/cloud.md +33 -33
  6. package/.bkit/core/.bkit/comparison.md +1 -1
  7. package/.bkit/core/.bkit/install.md +6 -5
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +4 -3
  10. package/.bkit/core/.bkit/prompts.md +4 -3
  11. package/.bkit/core/.bkit/providers.md +1 -1
  12. package/.bkit/core/.bkit/templates.md +35 -5
  13. package/.bkit/core/.bkit/trackers.md +7 -8
  14. package/.bkit/core/.bkit/workflows.md +106 -86
  15. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  16. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  17. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  23. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  25. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  26. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  28. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  29. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  30. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  32. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  34. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  36. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  37. package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
  38. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  39. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  40. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  43. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  44. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  47. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  48. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  49. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  50. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  51. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -0
  52. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  53. package/.bkit/core/engine/cli.ts +22 -15
  54. package/.bkit/core/engine/commands/comply.ts +25 -16
  55. package/.bkit/core/engine/commands/install/install.ts +11 -4
  56. package/.bkit/core/engine/commands/land.ts +156 -0
  57. package/.bkit/core/engine/commands/lib.ts +10 -8
  58. package/.bkit/core/engine/commands/registry.ts +2 -0
  59. package/.bkit/core/engine/commands/tips.ts +7 -3
  60. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  61. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  62. package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
  63. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  64. package/.bkit/core/engine/commands/workflow/prs.ts +11 -2
  65. package/.bkit/core/engine/commands/workflow/roadmap.ts +48 -53
  66. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  67. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  68. package/.bkit/core/engine/commands/workflow/steps.ts +24 -15
  69. package/.bkit/core/engine/commands/workflow/workflows.ts +433 -265
  70. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  71. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  72. package/.bkit/core/engine/install/modules/core.ts +15 -0
  73. package/.bkit/core/engine/install/placeholders.ts +13 -17
  74. package/.bkit/core/engine/shared/settings.ts +8 -0
  75. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  76. package/.bkit/core/prompts/bkit-audit-generate.md +47 -4
  77. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -1
  78. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -1
  79. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
  80. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -1
  81. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -1
  82. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +3 -3
  83. package/.bkit/core/workflows/bkit-auto.md +2 -2
  84. package/.bkit/core/workflows/bkit-build.md +7 -7
  85. package/.bkit/core/workflows/bkit-debug.md +11 -11
  86. package/.bkit/core/workflows/bkit-design.md +20 -11
  87. package/.bkit/core/workflows/bkit-plan.md +23 -13
  88. package/.bkit/core/workflows/bkit-ship.md +82 -93
  89. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  90. package/.bkit/shared/.claude/settings.json +1 -0
  91. package/.bkit/shared/docs/deployments.md +29 -25
  92. package/.bkit/shared/gitignore +1 -2
  93. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  94. package/.bkit/templates/.github/workflows/bkit-ci.yml +7 -2
  95. package/.bkit/templates/.husky/pre-commit +6 -0
  96. package/.bkit/templates/.husky/pre-push +7 -0
  97. package/.bkit/templates/.lintstagedrc.json +5 -1
  98. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  99. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  100. package/CHANGELOG.md +48 -0
  101. package/README.md +97 -96
  102. package/dist/checks/status-holes.js +0 -1
  103. package/dist/checks/tips/catalogue.js +14 -0
  104. package/dist/checks/tips/index.js +44 -28
  105. package/dist/cli.js +22 -16
  106. package/dist/commands/comply.js +20 -13
  107. package/dist/commands/install/install.js +10 -4
  108. package/dist/commands/land.js +129 -0
  109. package/dist/commands/lib.js +9 -6
  110. package/dist/commands/registry.js +2 -0
  111. package/dist/commands/tips.js +7 -3
  112. package/dist/commands/workflow/branches.js +300 -243
  113. package/dist/commands/workflow/disk.js +452 -0
  114. package/dist/commands/workflow/issues.js +63 -27
  115. package/dist/commands/workflow/locks.js +35 -130
  116. package/dist/commands/workflow/prs.js +5 -2
  117. package/dist/commands/workflow/roadmap.js +49 -56
  118. package/dist/commands/workflow/runtime.js +3 -2
  119. package/dist/commands/workflow/status.js +32 -12
  120. package/dist/commands/workflow/steps.js +18 -11
  121. package/dist/commands/workflow/workflows.js +388 -247
  122. package/dist/commands/workflow/workstreams.js +3 -2
  123. package/dist/commands/workflow/worktrees.js +11 -1
  124. package/dist/install/modules/core.js +13 -0
  125. package/dist/install/placeholders.js +13 -19
  126. package/dist/shared/settings.js +5 -0
  127. package/dist/shared/timeouts.js +8 -7
  128. package/package.json +1 -1
@@ -21,22 +21,22 @@ description: "Design Feature โ€” Autonomous design phase"
21
21
  > - **Finish:** `bkit steps finish` reads each `--agent`'s header from the `--artifact` in the same position, checks artifacts and row, writes the row, commits, prints `comment`. Exit 5 **or** 6 โ†’ invoke `reask.agent` again with `"Your prior output '<reask.artifact>' has an invalid header. Re-emit only its header fields + '<!-- verdict:end -->' at top of that file. Do not redo work."` โ†’ wait for subagent and re-run the block โ†’ **If** still non-zero โ†’ **Failure Path**. Hold `verdict` as the step's verdict, `fields` as its other header fields.
22
22
  > - **Resume:** On start, fold status.jsonl โ€” pick up after last `DONE` step in active `IN_PROGRESS` workflow.
23
23
  > - **Status:** `status.jsonl` = append-only NDJSON event log; fold to derive the run array. `step-done` carries `parentSha` captured at step START, optional `verdict` (`PASS|CONCERNS|FAIL`), `failures`, `attempt`, `strategy` (`STANDARD|PIVOT|FINAL`). **If** `failures` present โ†’ `PASS => failures=0`, `FAIL => failures>0`, `CONCERNS => failures>=0`.
24
- > - **Locks:** Step 1 takes `$REPO_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock` with `bkit locks acquire --kind=workflow` (hold `token`); release in last step with `bkit branches land` and in Failure Path with `bkit workflows fail`; a lock left in place โ†’ **Failure Path** with `Lock removal failed`. **If** existing lock โ€” its owning workflow's folded status.jsonl decides: `IN_PROGRESS` and last step <30min idle โ†’ **Failure Path**; any other holder (`DONE`, `FAILED`, `IN_PROGRESS` idle >=30min, no run) โ†’ reclaimed. **Dev lock:** `bkit branches land` holds `$REPO_ROOT/.bkit/.dev.lock` across every dev critical section (checkout / stage / commit / push of `dev` in the main checkout).
25
- > - **Status branch:** status.jsonl committed on `{BRANCH}` (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`); per-step commits, no mid-lifecycle pushes. **If** `runtimeDevPushes` = true โ†’ state reaches `dev` once in Close Workflow by local squash-merge. **Else** โ†’ PR squash-merge.
24
+ > - **Locks:** Step 1 takes `$REPO_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock` with `bkit locks acquire --kind=workflow` (hold `token`); release in last step with `bkit branches land` and in Failure Path with `bkit workflows fail`; a lock left in place โ†’ **Failure Path** with `Lock removal failed`. **If** existing lock โ€” its owning workflow's folded status.jsonl decides: `IN_PROGRESS` and last step <30min idle โ†’ **Failure Path**; any other holder (`DONE`, `FAILED`, `IN_PROGRESS` idle >=30min, no run) โ†’ reclaimed.
25
+ > - **Status branch:** status.jsonl committed on `{BRANCH}` (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`); per-step commits, no mid-lifecycle pushes. State reaches `dev` once, in Close Workflow: `bkit branches land` pushes a squash built off `origin/dev`, or squash-merges a PR when that push is refused.
26
26
  > - **Worktrees:** **If** `runtimeWorktrees` = true (mint mode) โ†’ setup `cd`s into `.worktrees/{FID}`. **Else** โ†’ adopt current branch in place, `WORKTREE_PATH=$REPO_ROOT`; no `git worktree add`. cwd persists across subsequent Bash calls. **If** steps ever find `pwd` != `{WORKTREE_PATH}` โ†’ **Failure Path**.
27
27
  > - **gh MCP fallback:** `gh` primary for PR / CI / merge surface. **If** a command exits 80, **or** `runtimeGithubCli` = false in the `runtime-resolved` row of `{STATUS}` โ†’ use mapped MCP tool (needs `actions` toolset in `.mcp.json`): `bkit prs open` / `bkit branches land` stage `open` โ†’ `create_pull_request` with the printed `title` / `body` / `base` / `head`; `bkit prs probe --number` โ†’ `pull_request_read` (`get`, minimal fields); `bkit prs probe --head` / `bkit workflows handover --push` โ†’ `list_pull_requests`; `bkit prs merge` / `bkit branches land` stage `merge` โ†’ `merge_pull_request` (printed skip-token-free `subject` as `commit_message`, empty body; `--match-head` SHA as `sha`); `bkit prs verbose-ci` โ†’ `update_pull_request`; `bkit prs update-branch --number` โ†’ `update_pull_request_branch`; `bkit prs checks --number` โ†’ `pull_request_read` (`get_status`); `bkit runs wait` / `bkit runs dispatch` / `bkit runs revalidate` / `bkit runs gate` โ†’ `actions_list`; `gh run view {id} --json jobs` โ†’ `actions_get`; `gh run view --log-failed` โ†’ `get_job_logs` (`failed_only=true`). Record via `bkit prs transport-row --file={STATUS} --kind=fallback --from=<gh command> --to=<MCP tool> --reason=<why> --asserted-by=<re-read>` โ€” **Skip if** `{STATUS}` not set. Tracker calls always stay on MCP; never invent `gh` read-paths for trackers.
28
28
 
29
29
  <!-- bkit:tracker github start -->
30
30
 
31
31
  > - **Tracker:** GitHub Issues via MCP server `github` (configured in `.mcp.json` `mcpServers.github`). Tool names: `mcp__github__issue_read` (methods `get`, `get_comments`, `get_labels`), `mcp__github__issue_write` (method: `update`), `mcp__github__add_issue_comment`, `mcp__github__list_issues`, `mcp__github__projects_write` (methods `add_project_item` / `update_project_item`), `mcp__github__projects_list` (method `list_project_items`) โ€” needs `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) and `package.json` `bkit.githubProject` config; absent either โ†’ board status sync silently skipped. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; all writes best-effort; never gate. **If** failure โ†’ retry once after 5s, then continue.
32
- > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:ship`, `bkit:merged` (mutually exclusive โ€” drop old phase before adding new). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path), `bkit:debug` (Debug workflow active, additive โ€” phase label persists). `bkit issues labels` computes each transition; MCP writes it.
32
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive โ€” drop old phase before adding new; a phase start also drops every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
33
33
  > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__github__add_issue_comment({ owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, body: "{BODY}" })` before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. Comment ID tracking not required.
34
34
 
35
35
  <!-- bkit:tracker github end -->
36
36
  <!-- bkit:tracker linear start -->
37
37
 
38
38
  > - **Tracker:** Linear via MCP server `linear` (configured in `.mcp.json` `mcpServers.linear`). Tool names: `mcp__linear__get_issue`, `mcp__linear__save_issue`, `mcp__linear__save_comment`, `mcp__linear__list_comments`, `mcp__linear__list_issues`. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; all `save_*` writes best-effort; never gate. **If** failure โ†’ retry once after 5s, then continue. `save_issue` always includes `id`.
39
- > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:ship`, `bkit:merged` (mutually exclusive โ€” drop old phase before adding new). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path), `bkit:debug` (Debug workflow active, additive โ€” phase label persists). `bkit issues labels` computes each transition; MCP writes it.
39
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive โ€” drop old phase before adding new; a phase start also drops every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
40
40
  > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id` โ€” creates new comment) before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. No edit-in-place.
41
41
 
42
42
  <!-- bkit:tracker linear end -->
@@ -54,7 +54,7 @@ description: "Design Feature โ€” Autonomous design phase"
54
54
  ```
55
55
  Route:
56
56
  - **If** exit 0 **or** 5 โ†’ hold `labels` as `{LABELS}`, `linearState` as `{LINEAR_STATE}` โ†’ step 2.
57
- - **Else** โ†’ step 3.
57
+ - **Else** โ†’ step 4.
58
58
  2. <!-- bkit:tracker github start -->
59
59
  Add `bkit:failed` (prior phase label persists, additive) โ†’ `mcp__github__issue_write({ method: "update", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, labels: [{LABELS}] })`.
60
60
  <!-- bkit:tracker github end -->
@@ -64,7 +64,14 @@ description: "Design Feature โ€” Autonomous design phase"
64
64
  <!-- bkit:tracker true start -->
65
65
  Post `comment` (when non-null).
66
66
  <!-- bkit:tracker true end -->
67
- 3. **STOP**, no further downstream steps.
67
+ 3. `git status --short` โ†’ on a feature branch remove unintended files; on `dev` / `main` remove nothing (only the run's own record lands, through a throwaway checkout). Then commit and push the run's record โ€” NEVER onto a branch with an open PR; **Skip if** `{WORKTREE_PATH}` is not set:
68
+ ```bash
69
+ "{BKIT}" workflows handover --workflow=design --fid={FID} --month={YYYYMM} --push --worktree="{WORKTREE_PATH}"
70
+ ```
71
+ Route:
72
+ - **If** exit 80 โ†’ open PR on `{BRANCH}` via `list_pull_requests` โ†’ re-run with `--open-pr={number}` or `--open-pr=none`.
73
+ - **Else** โ†’ post `comment` (when non-null) โ†’ step 4.
74
+ 4. **STOP**, no further downstream steps.
68
75
 
69
76
  ---
70
77
 
@@ -481,7 +488,7 @@ description: "Design Feature โ€” Autonomous design phase"
481
488
  "{BKIT}" workflows promote --workflow=design --fid={FID} --month={YYYYMM} --file="{STATUS}" || exit 1
482
489
  "{BKIT}" workflows close --workflow=design --fid={FID} --month={YYYYMM} --record-step --outbox="{OUTBOX}" --message="chore({FID}): close-workflow"
483
490
  ```
484
- 2. Land on `dev` โ€” local squash under the dev lock, else the PR squash-merge โ€” audit it, release the lock:
491
+ 2. Land on `dev` โ€” squash `{BRANCH}` onto `origin/dev` in a throwaway worktree and push it as `dev` (`dev` moved โ†’ rebuild and push again, with backoff); push refused โ†’ the PR squash-merge โ€” audit it, fast-forward local `dev` when that is a pure fast-forward, release the lock:
485
492
  ```bash
486
493
  cd "{REPO_ROOT}" && "{BKIT}" branches land --workflow=design --fid={FID} --month={YYYYMM} --token={LOCK_TOKEN} --issue="{ISSUE_ID}" --branch="{BRANCH}"
487
494
  ```
@@ -517,18 +524,20 @@ description: "Design Feature โ€” Autonomous design phase"
517
524
  <!-- bkit:tracker true start -->
518
525
  Append issue link [{ISSUE_ID} {TITLE}]({URL})
519
526
  <!-- bkit:tracker true end -->
527
+ **If** `## Outstanding Questions` lists any question โ†’ append `Want me to ask you the open questions one by one, with my recommendation for each? Then write 'yes, ask me one by one'.`
528
+ Append `Would you like me to explain any of this in plain English? Then write 'yes, explain in plain english'.`
520
529
  Append `{BKIT_TIPS}` under a `## bkit Tips` heading, unless empty.
521
- Append as last line `Would you like me to explain this in plain English?`
522
530
  7. **If** user requests plain English explanation โ†’ restate the summary in plain English; name terms and say what they mean; identifiers stay verbatim; plainness lives in sentences, NOT nouns; do not re-run any step.
531
+ 8. **If** user requests the open questions one by one โ†’ ask each `## Outstanding Questions` item on its own, verbatim, with its options, `Recommended` and `Default if unanswered`; wait for the answer before asking the next; do not re-run any step.
523
532
 
524
533
  ### ๐Ÿ”’ Gate 12 โ€” Close Workflow
525
534
 
526
535
  ```bash
527
- "{BKIT}" steps gate --file="{REPO_ROOT}/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl" --workflow=design --step=design-close-workflow
536
+ "{BKIT}" steps gate --file="{REPO_ROOT}/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl" --ref=origin/dev --workflow=design --step=design-close-workflow
528
537
  ```
529
538
 
530
- - [ ] Mechanical checks passed (`steps gate` exit 0: step `design-close-workflow` recorded)
531
- - [ ] Canonical design promoted and landed (`docs/plans/{YYYYMM}/{FID}-design.md` on `dev`, close telemetry committed; `branches land` exit 0: squash staged the `feat/{FID}` copy, body scan clean, transport row recorded, lock released)
539
+ - [ ] Mechanical checks passed (`steps gate` exit 0: step `design-close-workflow` recorded on `origin/dev`)
540
+ - [ ] Canonical design promoted and landed (`docs/plans/{YYYYMM}/{FID}-design.md` on `dev`, close telemetry committed; `branches land` exit 0: squash staged the `{BRANCH}` copy, body scan clean, transport cross-check passed, `close-transport` row written only when the run's checkout is the branch (`RUNTIME_DEVPUSHES=false`), otherwise logged โ€” the main checkout is never written to, lock released)
532
541
  - [ ] Worktree removed and feature branch deleted (workflow-created worktree only; branch kept when another worktree holds it, `branchBlockedBy`)
533
542
  - [ ] Final return displayed (`design-summary.md` content verbatim)
534
543
 
@@ -21,22 +21,22 @@ description: "Plan Feature โ€” Autonomous plan generation"
21
21
  > - **Finish:** `bkit steps finish` reads each `--agent`'s header from the `--artifact` in the same position, checks artifacts and row, writes the row, commits, prints `comment`. Exit 5 **or** 6 โ†’ invoke `reask.agent` again with `"Your prior output '<reask.artifact>' has an invalid header. Re-emit only its header fields + '<!-- verdict:end -->' at top of that file. Do not redo work."` โ†’ wait for subagent and re-run the block โ†’ **If** still non-zero โ†’ **Failure Path**. Hold `verdict` as the step's verdict, `fields` as its other header fields.
22
22
  > - **Resume:** On start, fold status.jsonl โ€” pick up after last `DONE` step in active `IN_PROGRESS` workflow.
23
23
  > - **Status:** `status.jsonl` = append-only NDJSON event log; fold to derive the run array. `step-done` carries `parentSha` captured at step START, optional `verdict` (`PASS|CONCERNS|FAIL`), `failures`, `attempt`, `strategy` (`STANDARD|PIVOT|FINAL`). **If** `failures` present โ†’ `PASS => failures=0`, `FAIL => failures>0`, `CONCERNS => failures>=0`.
24
- > - **Locks:** Step 1 takes `$REPO_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock` with `bkit locks acquire --kind=workflow` (hold `token`); release in last step with `bkit branches land` and in Failure Path with `bkit workflows fail`; a lock left in place โ†’ **Failure Path** with `Lock removal failed`. **If** existing lock โ€” its owning workflow's folded status.jsonl decides: `IN_PROGRESS` and last step <30min idle โ†’ **Failure Path**; any other holder (`DONE`, `FAILED`, `IN_PROGRESS` idle >=30min, no run) โ†’ reclaimed. **Dev lock:** `bkit branches land` holds `$REPO_ROOT/.bkit/.dev.lock` across every dev critical section (checkout / stage / commit / push of `dev` in the main checkout).
25
- > - **Status branch:** status.jsonl committed on `{BRANCH}` (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`); per-step commits, no mid-lifecycle pushes. **If** `runtimeDevPushes` = true โ†’ state reaches `dev` once in Close Workflow by local squash-merge. **Else** โ†’ PR squash-merge.
24
+ > - **Locks:** Step 1 takes `$REPO_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock` with `bkit locks acquire --kind=workflow` (hold `token`); release in last step with `bkit branches land` and in Failure Path with `bkit workflows fail`; a lock left in place โ†’ **Failure Path** with `Lock removal failed`. **If** existing lock โ€” its owning workflow's folded status.jsonl decides: `IN_PROGRESS` and last step <30min idle โ†’ **Failure Path**; any other holder (`DONE`, `FAILED`, `IN_PROGRESS` idle >=30min, no run) โ†’ reclaimed.
25
+ > - **Status branch:** status.jsonl committed on `{BRANCH}` (`$(git rev-parse --show-toplevel)/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`); per-step commits, no mid-lifecycle pushes. State reaches `dev` once, in Close Workflow: `bkit branches land` pushes a squash built off `origin/dev`, or squash-merges a PR when that push is refused.
26
26
  > - **Worktrees:** **If** `runtimeWorktrees` = true โ†’ Step 2 `bkit worktrees setup` mints / resumes `.worktrees/{FID}`. **Else** โ†’ adopts the current branch in place (`WORKTREE_PATH` = main checkout). Its block `cd`s into `worktreePath`. cwd persists across subsequent Bash calls. **If** steps ever find `pwd` != `{WORKTREE_PATH}` โ†’ **Failure Path**.
27
27
  > - **gh MCP fallback:** `gh` primary for PR / CI / merge surface. **If** a command exits 80, **or** `runtimeGithubCli` = false in the `runtime-resolved` row of `{STATUS}` โ†’ use mapped MCP tool (needs `actions` toolset in `.mcp.json`): `bkit prs open` / `bkit branches land` stage `open` โ†’ `create_pull_request` with the printed `title` / `body` / `base` / `head`; `bkit prs probe --number` โ†’ `pull_request_read` (`get`, minimal fields); `bkit prs probe --head` / `bkit workflows handover --push` โ†’ `list_pull_requests`; `bkit prs merge` / `bkit branches land` stage `merge` โ†’ `merge_pull_request` (printed skip-token-free `subject` as `commit_message`, empty body; `--match-head` SHA as `sha`); `bkit prs verbose-ci` โ†’ `update_pull_request`; `bkit prs update-branch --number` โ†’ `update_pull_request_branch`; `bkit prs checks --number` โ†’ `pull_request_read` (`get_status`); `bkit runs wait` / `bkit runs dispatch` / `bkit runs revalidate` / `bkit runs gate` โ†’ `actions_list`; `gh run view {id} --json jobs` โ†’ `actions_get`; `gh run view --log-failed` โ†’ `get_job_logs` (`failed_only=true`). Record via `bkit prs transport-row --file={STATUS} --kind=fallback --from=<gh command> --to=<MCP tool> --reason=<why> --asserted-by=<re-read>` โ€” **Skip if** `{STATUS}` not set. Tracker calls always stay on MCP; never invent `gh` read-paths for trackers.
28
28
 
29
29
  <!-- bkit:tracker github start -->
30
30
 
31
31
  > - **Tracker:** GitHub Issues via MCP server `github` (configured in `.mcp.json` `mcpServers.github`). Tool names: `mcp__github__issue_read` (methods `get`, `get_comments`, `get_labels`), `mcp__github__issue_write` (method: `update`), `mcp__github__add_issue_comment`, `mcp__github__list_issues`, `mcp__github__projects_write` (methods `add_project_item` / `update_project_item`), `mcp__github__projects_list` (method `list_project_items`) โ€” needs `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) and `package.json` `bkit.githubProject` config; absent either โ†’ board status sync silently skipped. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; all writes best-effort; never gate. **If** failure โ†’ retry once after 5s, then continue.
32
- > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:ship`, `bkit:merged` (mutually exclusive โ€” drop old phase before adding new). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path), `bkit:debug` (Debug workflow active, additive โ€” phase label persists). `bkit issues labels` computes each transition; MCP writes it.
32
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive โ€” drop old phase before adding new; a phase start also drops every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
33
33
  > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__github__add_issue_comment({ owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, body: "{BODY}" })` before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. Comment ID tracking not required.
34
34
 
35
35
  <!-- bkit:tracker github end -->
36
36
  <!-- bkit:tracker linear start -->
37
37
 
38
38
  > - **Tracker:** Linear via MCP server `linear` (configured in `.mcp.json` `mcpServers.linear`). Tool names: `mcp__linear__get_issue`, `mcp__linear__save_issue`, `mcp__linear__save_comment`, `mcp__linear__list_comments`, `mcp__linear__list_issues`. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; all `save_*` writes best-effort; never gate. **If** failure โ†’ retry once after 5s, then continue. `save_issue` always includes `id`.
39
- > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:ship`, `bkit:merged` (mutually exclusive โ€” drop old phase before adding new). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path), `bkit:debug` (Debug workflow active, additive โ€” phase label persists). `bkit issues labels` computes each transition; MCP writes it.
39
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive โ€” drop old phase before adding new; a phase start also drops every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
40
40
  > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id` โ€” creates new comment) before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. No edit-in-place.
41
41
 
42
42
  <!-- bkit:tracker linear end -->
@@ -54,7 +54,7 @@ description: "Plan Feature โ€” Autonomous plan generation"
54
54
  ```
55
55
  Route:
56
56
  - **If** exit 0 **or** 5 โ†’ hold `labels` as `{LABELS}`, `linearState` as `{LINEAR_STATE}` โ†’ step 2.
57
- - **Else** โ†’ step 3.
57
+ - **Else** โ†’ step 4.
58
58
  2. <!-- bkit:tracker github start -->
59
59
  `mcp__github__issue_write({ method: "update", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, labels: [{LABELS}] })`.
60
60
  <!-- bkit:tracker github end -->
@@ -64,7 +64,14 @@ description: "Plan Feature โ€” Autonomous plan generation"
64
64
  <!-- bkit:tracker true start -->
65
65
  Post `comment` (when non-null).
66
66
  <!-- bkit:tracker true end -->
67
- 3. **STOP**, no further downstream steps.
67
+ 3. `git status --short` โ†’ on a feature branch remove unintended files; on `dev` / `main` remove nothing (only the run's own record lands, through a throwaway checkout). Then commit and push the run's record โ€” NEVER onto a branch with an open PR; **Skip if** `{WORKTREE_PATH}` is not set:
68
+ ```bash
69
+ "{BKIT}" workflows handover --workflow=plan --fid={FID} --month={YYYYMM} --push --worktree="{WORKTREE_PATH}"
70
+ ```
71
+ Route:
72
+ - **If** exit 80 โ†’ open PR on `{BRANCH}` via `list_pull_requests` โ†’ re-run with `--open-pr={number}` or `--open-pr=none`.
73
+ - **Else** โ†’ post `comment` (when non-null) โ†’ step 4.
74
+ 4. **STOP**, no further downstream steps.
68
75
 
69
76
  ---
70
77
 
@@ -122,7 +129,7 @@ description: "Plan Feature โ€” Autonomous plan generation"
122
129
  ```
123
130
  Hold `token` as `{LOCK_TOKEN}`, `month` as `{YYYYMM}`.
124
131
  6. Extract plan inputs from issue `DESCRIPTION` and the session prompt.
125
- - `PARENT_FID`: a `**Parent design:**` markdown link whose target is `docs/plans/{YYYYMM}/{FID}-design.md`. `PARENT_YYYYMM` = that bucket. Absent โ†’ this feature's own design doc:
132
+ - `PARENT_FID`: a `**Parent design:**` markdown link whose target ends in `docs/plans/{YYYYMM}/{FID}-design.md`. `PARENT_YYYYMM` = that bucket. Absent โ†’ this feature's own design doc:
126
133
  ```bash
127
134
  "{BKIT}" fids design --fid={FID} --month={YYYYMM}
128
135
  ```
@@ -153,8 +160,9 @@ description: "Plan Feature โ€” Autonomous plan generation"
153
160
  8. <!-- bkit:tracker true start -->
154
161
  Comment:
155
162
  ```bash
156
- "{BKIT}" issues comment --workflow=plan --workflow-heading --step-number=1 --step-title="Start Workflow" --owner-repo={OWNER_REPO} --tree=dev --line="Parent design: {None|[{PARENT_FID}-design.md](https://github.com/{OWNER_REPO}/blob/main/docs/plans/{PARENT_YYYYMM}/{PARENT_FID}-design.md)}" --line="Audit reports: {None|{AUDIT_PATHS}}"
163
+ "{BKIT}" issues comment --workflow=plan --workflow-heading --step-number=1 --step-title="Start Workflow" --owner-repo={OWNER_REPO} --tree=dev --line="Parent design: {None|[{PARENT_FID}-design.md](https://github.com/{OWNER_REPO}/blob/dev/docs/plans/{PARENT_YYYYMM}/{PARENT_FID}-design.md)}" --line="Audit reports: {None|[{AUDIT_FILE}](https://github.com/{OWNER_REPO}/blob/dev/{AUDIT_PATH})}"
157
164
  ```
165
+ `Audit reports`: one link per `AUDIT_PATHS` entry, comma-separated; `{AUDIT_FILE}` = file name of `{AUDIT_PATH}`.
158
166
  <!-- bkit:tracker true end -->
159
167
 
160
168
  ### ๐Ÿ”’ Gate 1 โ€” Start Workflow
@@ -459,7 +467,7 @@ description: "Plan Feature โ€” Autonomous plan generation"
459
467
  "{BKIT}" workflows promote --workflow=plan --fid={FID} --month={YYYYMM} --file="{STATUS}" || exit 1
460
468
  "{BKIT}" workflows close --workflow=plan --fid={FID} --month={YYYYMM} --record-step --outbox="{OUTBOX}" --message="chore({FID}): close-workflow"
461
469
  ```
462
- 2. Land on `dev` โ€” local squash under the dev lock, else the PR squash-merge โ€” audit it, release the lock:
470
+ 2. Land on `dev` โ€” squash `{BRANCH}` onto `origin/dev` in a throwaway worktree and push it as `dev` (`dev` moved โ†’ rebuild and push again, with backoff); push refused โ†’ the PR squash-merge โ€” audit it, fast-forward local `dev` when that is a pure fast-forward, release the lock:
463
471
  ```bash
464
472
  cd "{REPO_ROOT}" && "{BKIT}" branches land --workflow=plan --fid={FID} --month={YYYYMM} --token={LOCK_TOKEN} --issue="{ISSUE_ID}" --branch="{BRANCH}"
465
473
  ```
@@ -502,18 +510,20 @@ description: "Plan Feature โ€” Autonomous plan generation"
502
510
  <!-- bkit:tracker true start -->
503
511
  Append issue link [{ISSUE_ID} {TITLE}]({URL})
504
512
  <!-- bkit:tracker true end -->
513
+ **If** `## Outstanding Questions` lists any question โ†’ append `Want me to ask you the open questions one by one, with my recommendation for each? Then write 'yes, ask me one by one'.`
514
+ Append `Would you like me to explain any of this in plain English? Then write 'yes, explain in plain english'.`
505
515
  Append `{BKIT_TIPS}` under a `## bkit Tips` heading, unless empty.
506
- Append as last line `Would you like me to explain this in plain English?`
507
516
  7. **If** user requests plain English explanation โ†’ restate the summary in plain English; name terms and say what they mean; identifiers stay verbatim; plainness lives in sentences, NOT nouns; do not re-run any step.
517
+ 8. **If** user requests the open questions one by one โ†’ ask each `## Outstanding Questions` item on its own, verbatim, with its options, `Recommended` and `Default if unanswered`; wait for the answer before asking the next; do not re-run any step.
508
518
 
509
519
  ### ๐Ÿ”’ Gate 12 โ€” Close Workflow
510
520
 
511
521
  ```bash
512
- "{BKIT}" steps gate --file="{REPO_ROOT}/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl" --workflow=plan --step=plan-close-workflow
522
+ "{BKIT}" steps gate --file="{REPO_ROOT}/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl" --ref=origin/dev --workflow=plan --step=plan-close-workflow
513
523
  ```
514
524
 
515
- - [ ] Mechanical checks passed (`steps gate` exit 0: step `plan-close-workflow` recorded)
516
- - [ ] Canonical plan promoted and landed (`docs/plans/{YYYYMM}/{FID}-plan.md` and sub-plans on `dev`, close telemetry committed; `branches land` exit 0: squash staged the `feat/{FID}` copies, body scan clean, transport row recorded, lock released)
525
+ - [ ] Mechanical checks passed (`steps gate` exit 0: step `plan-close-workflow` recorded on `origin/dev`)
526
+ - [ ] Canonical plan promoted and landed (`docs/plans/{YYYYMM}/{FID}-plan.md` and sub-plans on `dev`, close telemetry committed; `branches land` exit 0: squash staged the `{BRANCH}` copies, body scan clean, transport cross-check passed, `close-transport` row written only when the run's checkout is the branch (`RUNTIME_DEVPUSHES=false`), otherwise logged โ€” the main checkout is never written to, lock released)
517
527
  - [ ] Worktree removed and feature branch deleted (workflow-created worktree only; branch kept when another worktree holds it, `branchBlockedBy`)
518
528
  - [ ] Final return displayed (`plan-summary.md` content verbatim)
519
529
 
@@ -17,26 +17,26 @@ description: "Ship Feature โ€” Autonomous merge and archive"
17
17
  > - **`Failures`:** **If** any step, tool, command fails, or gate cannot pass โ†’ **Failure Path**.
18
18
  > - **Friction:** Watch own context and subagent returns for human confirm prompts, manual installs, agent rework, repeated tool failures, destructive backouts โ†’ append rows to `.bkit/friction.jsonl` in `.bkit/jsonl.md` format โ†’ continue or escalate; logging does not replace **Failure Path**.
19
19
  > - **Placeholders:** Assert `{PLACEHOLDERS}` such as `{FID}`, `{YYYYMM}`, etc non-empty if required before making tool calls. **Else** โ†’ **Failure Path**.
20
- > - **Commands:** Blocks run `"{BKIT}" <noun> <verb> --flag=value`; `{BKIT}` = `bkit` printed by Step 1 `repo info`, until then `"$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit"`. Stdout is one JSON object: hold named keys as `{VAR}`. Exit non-zero with no `Route:` for it โ†’ **Failure Path**; exit 80 โ†’ mapped MCP tool (**gh MCP fallback**); exit 81 โ†’ end turn, re-run block. A flag still holding a literal `{PLACEHOLDER}` exits 2. `--dev-pushes` goes on a call only when `RUNTIME_DEVPUSHES` = true.
20
+ > - **Commands:** Blocks run `"{BKIT}" <noun> <verb> --flag=value`; `{BKIT}` = `bkit` printed by Step 1 `repo info`, until then `"$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit"`. Stdout is one JSON object: hold named keys as `{VAR}`. Exit non-zero with no `Route:` for it โ†’ **Failure Path**; exit 80 โ†’ mapped MCP tool (**gh MCP fallback**); exit 81 โ†’ end turn, re-run block. A flag still holding a literal `{PLACEHOLDER}` exits 2.
21
21
  > - **Finish:** `bkit steps finish` reads each `--agent`'s header from the `--artifact` in the same position, derives the attempt (`--attempt-of`; `<attempt>` in a path becomes it), checks artifacts and row, writes the row (ship: `--commit=none`, bookkeeping to `$BOOK_ROOT`), prints `comment`. Exit 5 **or** 6 โ†’ invoke `reask.agent` again with `"Your prior output '<reask.artifact>' has an invalid header. Re-emit only its header fields + '<!-- verdict:end -->' at top of that file. Do not redo work."` โ†’ wait for subagent and re-run the block โ†’ **If** still non-zero โ†’ **Failure Path**. Hold `verdict` as the step's verdict, `fields` as its other header fields, `attempt` as its attempt.
22
22
  > - **Resume:** On start, fold `$BOOK_ROOT/.../status.jsonl` โ€” pick up after last `DONE` step in active `IN_PROGRESS` workflow.
23
23
  > - **Status:** `$BOOK_ROOT/.../status.jsonl` = append-only NDJSON event log; fold to derive the run array. `step-done` carries `parentSha` captured at step START, optional `verdict` (`PASS|CONCERNS|FAIL`), `failures`, `attempt`, `strategy` (`STANDARD|PIVOT|FINAL`). **If** `failures` present โ†’ `PASS => failures=0`, `FAIL => failures>0`, `CONCERNS => failures>=0`.
24
- > - **Locks:** Step 1 takes `$BOOK_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock` with `bkit locks acquire --kind=workflow` (hold `token`); Step 15 releases it via `bkit workflows close --flush --token=`, the **Failure Path** via `bkit workflows fail --token=`. **If** existing lock โ€” its owning workflow's folded status.jsonl decides: `IN_PROGRESS` and last step <30min idle โ†’ **Failure Path**; any other holder (`DONE`, `FAILED`, `IN_PROGRESS` idle >=30min, no run) โ†’ reclaimed. **Dev lock:** `bkit branches switch`, `bkit workflows close --flush` and `bkit workflows handover --flush` hold `$REPO_ROOT/.bkit/.dev.lock` across every dev critical section (checkout / stage / commit / push of `dev` in the main checkout).
25
- > - **Status branch:** All steps write `$BOOK_ROOT/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` (`{STATUS}`). **If** `RUNTIME_DEVPUSHES` = true โ†’ `BOOK_ROOT` = `$REPO_ROOT`. **Else** โ†’ current working branch tree. Stage path-scoped via `bkit ledgers commit`; NEVER stage all files (`-A`) or blanket `docs/`. one commit per flush block: Commit + Push Bookkeeping โ†’ `docs({FID}): ship bookkeeping bkit [skip ci]` โ†’ push `{SHIP_BRANCH}` (pre-merge: docs, logs, ledgers, skill removals); Close Workflow โ†’ `docs({FID}): ship DONE bkit [skip ci]` โ†’ push `dev`, refused โ†’ close PR; **Failure Path** โ†’ `chore({FID}): ship FAILED bkit [skip ci]` โ†’ **If** `RUNTIME_DEVPUSHES` = true โ†’ push `dev`. **Else** โ†’ current branch. never both.
26
- > - **Worktrees:** **If** `runtimeWorktrees` = true (mint mode) โ†’ Step 2 `cd`s into `.worktrees/{FID}`. **Else** โ†’ adopt current branch in place, `WORKTREE_PATH=$REPO_ROOT`. cwd persists across subsequent Bash calls. **If** steps ever find `pwd` != `{WORKTREE_PATH}` โ†’ **Failure Path**.
24
+ > - **Locks:** Step 1 takes `$REPO_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock` with `bkit locks acquire --kind=workflow` (hold `token`); Step 14 releases it via `bkit workflows close --flush --token=`, the **Failure Path** via `bkit workflows fail --token=`. **If** existing lock โ€” its owning workflow's folded status.jsonl decides: `IN_PROGRESS` and last step <30min idle โ†’ **Failure Path**; any other holder (`DONE`, `FAILED`, `IN_PROGRESS` idle >=30min, no run) โ†’ reclaimed.
25
+ > - **Status branch:** From Step 2 all steps write `$BOOK_ROOT/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` (`{STATUS}`); `BOOK_ROOT` = `{WORKTREE_PATH}`. Stage path-scoped via `bkit ledgers commit`; NEVER stage all files (`-A`) or blanket `docs/`. one commit per flush block: Commit + Push Bookkeeping โ†’ `docs({FID}): ship bookkeeping bkit [skip ci]` โ†’ push `{SHIP_BRANCH}` (pre-merge: docs, logs, ledgers, skill removals); Close Workflow โ†’ `docs({FID}): ship DONE bkit [skip ci]`, **Failure Path** โ†’ `chore({FID}): ship FAILED bkit [skip ci]` โ†’ push `dev` from a throwaway `origin/dev` checkout; a refused close push โ†’ close PR.
26
+ > - **Worktrees:** **If** `runtimeWorktrees` = true (mint mode) โ†’ Step 2 `cd`s into `.worktrees/{FID}`. **Else** โ†’ adopt current branch in place, `WORKTREE_PATH=$REPO_ROOT`. cwd persists across subsequent Bash calls. **If** steps ever find `pwd` != `{WORKTREE_PATH}` โ†’ **Failure Path**; Step 14 ends in `{REPO_ROOT}`.
27
27
  > - **gh MCP fallback:** `gh` primary for PR / CI / merge surface. **If** a command exits 80, **or** `runtimeGithubCli` = false in the `runtime-resolved` row of `{STATUS}` โ†’ use mapped MCP tool (needs `actions` toolset in `.mcp.json`): `bkit prs open` / `bkit branches land` stage `open` โ†’ `create_pull_request` with the printed `title` / `body` / `base` / `head`; `bkit prs probe --number` โ†’ `pull_request_read` (`get`, minimal fields); `bkit prs probe --head` / `bkit workflows handover --push` โ†’ `list_pull_requests`; `bkit prs merge` / `bkit branches land` stage `merge` โ†’ `merge_pull_request` (printed skip-token-free `subject` as `commit_message`, empty body; `--match-head` SHA as `sha`); `bkit prs verbose-ci` โ†’ `update_pull_request`; `bkit prs update-branch --number` โ†’ `update_pull_request_branch`; `bkit prs checks --number` โ†’ `pull_request_read` (`get_status`); `bkit runs wait` / `bkit runs dispatch` / `bkit runs revalidate` / `bkit runs gate` โ†’ `actions_list`; `gh run view {id} --json jobs` โ†’ `actions_get`; `gh run view --log-failed` โ†’ `get_job_logs` (`failed_only=true`). Record via `bkit prs transport-row --file={STATUS} --kind=fallback --from=<gh command> --to=<MCP tool> --reason=<why> --asserted-by=<re-read>` โ€” **Skip if** `{STATUS}` not set. Tracker calls always stay on MCP; never invent `gh` read-paths for trackers.
28
28
 
29
29
  <!-- bkit:tracker github start -->
30
30
 
31
31
  > - **Tracker:** GitHub Issues via MCP server `github` (configured in `.mcp.json` `mcpServers.github`). Tool names: `mcp__github__issue_read` (methods `get`, `get_comments`, `get_labels`), `mcp__github__issue_write` (method: `update`), `mcp__github__add_issue_comment`, `mcp__github__list_issues`, `mcp__github__projects_write` (methods `add_project_item` / `update_project_item`), `mcp__github__projects_list` (method `list_project_items`) โ€” needs `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) and `package.json` `bkit.githubProject` config; absent either โ†’ board status sync silently skipped. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; all writes best-effort; never gate. **If** failure โ†’ retry once after 5s, then continue.
32
- > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:ship`, `bkit:merged` (mutually exclusive โ€” drop old phase before adding new). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path), `bkit:debug` (Debug workflow active, additive โ€” phase label persists). `bkit issues labels` computes each transition; MCP writes it.
32
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive โ€” drop old phase before adding new; a phase start also drops every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
33
33
  > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__github__add_issue_comment({ owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, body: "{BODY}" })` before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. Comment ID tracking not required.
34
34
 
35
35
  <!-- bkit:tracker github end -->
36
36
  <!-- bkit:tracker linear start -->
37
37
 
38
38
  > - **Tracker:** Linear via MCP server `linear` (configured in `.mcp.json` `mcpServers.linear`). Tool names: `mcp__linear__get_issue`, `mcp__linear__save_issue`, `mcp__linear__save_comment`, `mcp__linear__list_comments`, `mcp__linear__list_issues`. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; all `save_*` writes best-effort; never gate. **If** failure โ†’ retry once after 5s, then continue. `save_issue` always includes `id`.
39
- > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:ship`, `bkit:merged` (mutually exclusive โ€” drop old phase before adding new). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path), `bkit:debug` (Debug workflow active, additive โ€” phase label persists). `bkit issues labels` computes each transition; MCP writes it.
39
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive โ€” drop old phase before adding new; a phase start also drops every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
40
40
  > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id` โ€” creates new comment) before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. No edit-in-place.
41
41
 
42
42
  <!-- bkit:tracker linear end -->
@@ -54,7 +54,7 @@ description: "Ship Feature โ€” Autonomous merge and archive"
54
54
 
55
55
  1. Write the error message / tool response to `{OUTBOX_ROOT}/error.md` (`--error-file` dropped while `{OUTBOX_ROOT}` is not held). `{STDERR_FILE}` = `{OUTBOX}/stderr.log` holding the failed shell command's stderr โ€” drop `--stderr-file` when the failure was not a shell command or `{OUTBOX}` is not set yet; drop `--token` when `{LOCK_TOKEN}` is empty, `--pr` when `{PR_NUMBER}` is empty; `--max-exceeded` only when a `counters route` exit 1 (a `MAX_*` limit) sent the run here; `{LABEL_FLAGS}` = one `--label=<name>` per current `LABELS` entry. Abort any in-progress rebase, record the failure, release the lock, clear sentinels โ€” **state only, no `add` / `commit` / `push`**; a MERGED PR moves the issue to `bkit:merged` plus `bkit:failed`, else the prior phase label persists:
56
56
  ```bash
57
- "{BKIT}" workflows fail --workflow=ship --fid={FID} --month={YYYYMM} --token={LOCK_TOKEN} --dev-pushes --max-exceeded --pr={PR_NUMBER} {LABEL_FLAGS} --step-number={N} --step-title="{Step Name}" --sub-step={M} --error-file="{OUTBOX_ROOT}/error.md" --stderr-file="{STDERR_FILE}"
57
+ "{BKIT}" workflows fail --workflow=ship --fid={FID} --month={YYYYMM} --token={LOCK_TOKEN} --max-exceeded --pr={PR_NUMBER} {LABEL_FLAGS} --step-number={N} --step-title="{Step Name}" --sub-step={M} --error-file="{OUTBOX_ROOT}/error.md" --stderr-file="{STDERR_FILE}"
58
58
  ```
59
59
  โ†’ hold `handoverNeeded` as `{HANDOVER_NEEDED}`, `labels` as `{LABELS}`. **If** exit non-zero โ†’ log `Lock removal failed` with the printed `lock` to stderr, continue.
60
60
  2. <!-- bkit:tracker github start -->
@@ -71,9 +71,9 @@ description: "Ship Feature โ€” Autonomous merge and archive"
71
71
  Context: You are a subagent in the Ship Debug phase. Switch into working directory `cd "{WORKTREE_PATH}"` โ†’ verify with `pwd` โ†’ use for all subsequent file operations.
72
72
  Read: `{STATUS}`, `docs/plans/{YYYYMM}/logs/{FID}/ship-input-{RUN}.md` (if present), `docs/plans/{YYYYMM}/logs/{FID}/ship-deferred-sweep.md` (if present), glob `docs/plans/{YYYYMM}/logs/{FID}/ship-failure-diagnose-*.md`, glob `docs/plans/{YYYYMM}/logs/{FID}/ship-failure-remediate-*-log.md`, `git diff origin/dev..HEAD` (apply **Large Diff Guard**).
73
73
  Create: `docs/plans/{YYYYMM}/logs/{FID}/ship-handover.md`.
74
- 5. Reconcile branch-side artifacts into `BOOK_ROOT`, then flush one commit and one push โ€” **Skip if** `{FID}` or `{YYYYMM}` empty; drop `--worktree` when `{WORKTREE_PATH}` is not set:
74
+ 5. Flush the run's book to `dev` as one commit and one push โ€” **Skip if** `{FID}` or `{YYYYMM}` empty; drop `--worktree` when `{WORKTREE_PATH}` is not set:
75
75
  ```bash
76
- "{BKIT}" workflows handover --workflow=ship --fid={FID} --month={YYYYMM} --flush --dev-pushes --worktree="{WORKTREE_PATH}"
76
+ "{BKIT}" workflows handover --workflow=ship --fid={FID} --month={YYYYMM} --flush --worktree="{WORKTREE_PATH}"
77
77
  ```
78
78
  **If** `HANDOVER_NEEDED` = true **and** `comment` non-null โ†’ post `comment` (handover linked only where the flush pushed it). **If** the push failed โ†’ do not claim success on tracker.
79
79
  6. **STOP**, no further downstream steps.
@@ -131,13 +131,34 @@ description: "Ship Feature โ€” Autonomous merge and archive"
131
131
  ```bash
132
132
  "{BKIT}" runtime detect --fid="{FID}"
133
133
  ```
134
- โ†’ hold `runtimeDevPushes` as `{RUNTIME_DEVPUSHES}`, `runtimeWorktrees` as `{RUNTIME_WORKTREES}`.
134
+ โ†’ hold `runtimeWorktrees` as `{RUNTIME_WORKTREES}`.
135
135
  6. Acquire concurrency lock:
136
136
  ```bash
137
- "{BKIT}" locks acquire --kind=workflow --workflow=ship --fid="{FID}" --dev-pushes
137
+ "{BKIT}" locks acquire --kind=workflow --workflow=ship --fid="{FID}"
138
138
  ```
139
139
  โ†’ hold `token` as `{LOCK_TOKEN}`, `month` as `{YYYYMM}`.
140
- 7. <!-- bkit:tracker true start -->
140
+ 7. Resolve `SHIP_BRANCH`, then create / resume worktree, or adopt it in place (no rebase โ€” Path A) โ€” straight after the lock, so every later failure has a book to keep its record in; `--branch` = the branch the session prompt names, dropped when it names none:
141
+ ```bash
142
+ "{BKIT}" worktrees setup --workflow=ship --fid="{FID}" --month="{YYYYMM}" --detect --branch="{PROMPT_BRANCH}"
143
+ ```
144
+ โ†’ hold `worktreePath` as `{WORKTREE_PATH}`, `branch` as `{SHIP_BRANCH}`.
145
+ 8. Enter the worktree and find where the run books:
146
+ ```bash
147
+ cd "{WORKTREE_PATH}" || exit 1
148
+ [ "$(git branch --show-current)" = "{SHIP_BRANCH}" ] || { echo "[bkit-ship] not on {SHIP_BRANCH} in {WORKTREE_PATH}" >&2; exit 1; }
149
+ "{BKIT}" status path --workflow=ship --fid="{FID}" --month="{YYYYMM}"
150
+ ```
151
+ โ†’ hold `path` as `{STATUS}`, `bookRoot` as `{BOOK_ROOT}`. Open the run โ€” clear stale sentinels, write `workflow-started` and `ship-start-workflow` rows โ€” and record the runtime:
152
+ ```bash
153
+ rm -f "{BOOK_ROOT}/docs/plans/{YYYYMM}/logs/{FID}/.deferred-blocked" "{BOOK_ROOT}/docs/plans/{YYYYMM}/logs/{FID}/.rebase-failed"
154
+ "{BKIT}" workflows start --workflow=ship --fid="{FID}" --month="{YYYYMM}" --file="{STATUS}" --lock-held --token="{LOCK_TOKEN}" || exit 1
155
+ "{BKIT}" steps done --workflow=ship --step=ship-start-workflow --file="{STATUS}" --commit=none >/dev/null || exit 1
156
+ "{BKIT}" runtime row --workflow=ship --file="{STATUS}" >/dev/null || exit 1
157
+ "{BKIT}" runtime assert --workflow=ship --file="{STATUS}" >/dev/null
158
+ ```
159
+ โ†’ hold `run` as `{RUN}`.
160
+ Update `BRANCH` = `SHIP_BRANCH`; carry `SHIP_BRANCH` to every later step.
161
+ 9. <!-- bkit:tracker true start -->
141
162
  Compute the label transition and board move โ€” `{LABEL_FLAGS}` = one `--label=<name>` per current `LABELS` entry:
142
163
  ```bash
143
164
  "{BKIT}" issues labels --phase=ship --board=progress --issue="{ISSUE_ID}" --owner-repo="{OWNER_REPO}" {LABEL_FLAGS}
@@ -151,25 +172,17 @@ description: "Ship Feature โ€” Autonomous merge and archive"
151
172
  <!-- bkit:tracker linear start -->
152
173
  `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "In Progress", labels: [{LABELS}] })`.
153
174
  <!-- bkit:tracker linear end -->
154
- 8. Find where the run books, then open it โ€” clear stale sentinels, write `workflow-started` and `ship-start-workflow` rows:
155
- ```bash
156
- "{BKIT}" status path --workflow=ship --fid="{FID}" --month="{YYYYMM}" --dev-pushes
157
- ```
158
- โ†’ hold `path` as `{STATUS}`, `bookRoot` as `{BOOK_ROOT}`; `{OUTBOX}` = `{OUTBOX_ROOT}/{FID}`.
159
- ```bash
160
- mkdir -p "{OUTBOX}" || exit 1
161
- rm -f "{BOOK_ROOT}/docs/plans/{YYYYMM}/logs/{FID}/.deferred-blocked" "{BOOK_ROOT}/docs/plans/{YYYYMM}/logs/{FID}/.rebase-failed"
162
- "{BKIT}" workflows start --workflow=ship --fid="{FID}" --month="{YYYYMM}" --file="{STATUS}" --lock-held --token="{LOCK_TOKEN}" --dev-pushes || exit 1
163
- "{BKIT}" steps done --workflow=ship --step=ship-start-workflow --file="{STATUS}" --commit=none >/dev/null || exit 1
164
- "{BKIT}" repo preflight --owner-repo="{OWNER_REPO}"
165
- ```
166
- โ†’ hold `run` as `{RUN}`.
167
- 9. Write `DESCRIPTION` to `{OUTBOX}/issue-description.md` and `COMMENTS` as read to `{OUTBOX}/issue-comments.json` (empty / `[]` when no tracker), then build `ISSUE_TEXT`:
168
- ```bash
169
- "{BKIT}" issues text --description-file="{OUTBOX}/issue-description.md" --comments-file="{OUTBOX}/issue-comments.json"
170
- ```
171
- โ†’ hold `text` as `{ISSUE_TEXT}`.
172
- 10. <!-- bkit:tracker true start -->
175
+ 10. Create the outbox (`{OUTBOX}` = `{OUTBOX_ROOT}/{FID}`) and run the repo preflight:
176
+ ```bash
177
+ mkdir -p "{OUTBOX}" || exit 1
178
+ "{BKIT}" repo preflight --owner-repo="{OWNER_REPO}"
179
+ ```
180
+ 11. Write `DESCRIPTION` to `{OUTBOX}/issue-description.md` and `COMMENTS` as read to `{OUTBOX}/issue-comments.json` (empty / `[]` when no tracker), then build `ISSUE_TEXT`:
181
+ ```bash
182
+ "{BKIT}" issues text --description-file="{OUTBOX}/issue-description.md" --comments-file="{OUTBOX}/issue-comments.json"
183
+ ```
184
+ โ†’ hold `text` as `{ISSUE_TEXT}`.
185
+ 12. <!-- bkit:tracker true start -->
173
186
  Comment:
174
187
  ```bash
175
188
  "{BKIT}" issues comment --workflow=ship --workflow-heading --step-number=1 --step-title="Start Workflow" --owner-repo="{OWNER_REPO}" --tree="{BRANCH}"
@@ -179,12 +192,13 @@ description: "Ship Feature โ€” Autonomous merge and archive"
179
192
  ### ๐Ÿ”’ Gate 1 โ€” Start Workflow
180
193
 
181
194
  ```bash
182
- "{BKIT}" steps gate --file="{STATUS}" --workflow=ship --step=ship-start-workflow --fid={FID} --month={YYYYMM} --token={LOCK_TOKEN} --dev-pushes --placeholder=OWNER_REPO={OWNER_REPO} --placeholder=BRANCH={BRANCH} --placeholder=BOOK_ROOT={BOOK_ROOT} --placeholder=RUNTIME_DEVPUSHES={RUNTIME_DEVPUSHES} --placeholder=RUNTIME_WORKTREES={RUNTIME_WORKTREES}
195
+ "{BKIT}" steps gate --workflow=ship --step=ship-start-workflow --fid={FID} --month={YYYYMM} --token={LOCK_TOKEN} --placeholder=OWNER_REPO={OWNER_REPO} --placeholder=BRANCH={BRANCH} --placeholder=RUNTIME_WORKTREES={RUNTIME_WORKTREES}
183
196
  ```
184
197
 
185
- - [ ] Mechanical checks passed (`steps gate` exit 0: placeholders and runtime held, FID shape, lock held, step `ship-start-workflow` recorded)
198
+ - [ ] Mechanical checks passed (`steps gate` exit 0: placeholders held, FID shape, lock held)
186
199
  - [ ] Issue ID resolved (`ISSUE_ID` non-empty when tracker wired; may be empty under `none`)
187
- - [ ] Outbox created, stale sentinels cleared, run number set (`{OUTBOX}`, `.deferred-blocked`, `.rebase-failed`, `{RUN}`)
200
+ - [ ] On `SHIP_BRANCH` (not `dev|main`), worktree created / resumed or adopted (no rebase โ€” Path A) before any tracker write; run opened in the worktree (`workflow-started`, `ship-start-workflow`, `runtime-resolved`)
201
+ - [ ] Outbox created (`{OUTBOX}`)
188
202
 
189
203
  <!-- bkit:tracker true start -->
190
204
 
@@ -196,29 +210,16 @@ description: "Ship Feature โ€” Autonomous merge and archive"
196
210
 
197
211
  ## ๐Ÿค– Step 2 โ€” Verify PR (Worktree Setup + Regression Guard)
198
212
 
199
- 1. Resolve `SHIP_BRANCH`, then create / resume worktree, or adopt it in place (no rebase โ€” Path A); `--branch` = the branch the session prompt names, dropped when it names none:
200
- ```bash
201
- "{BKIT}" worktrees setup --workflow=ship --fid="{FID}" --month="{YYYYMM}" --detect --branch="{PROMPT_BRANCH}"
202
- ```
203
- โ†’ hold `worktreePath` as `{WORKTREE_PATH}`, `branch` as `{SHIP_BRANCH}`.
204
- 2. Enter the worktree and record the runtime:
205
- ```bash
206
- cd "{WORKTREE_PATH}" || exit 1
207
- [ "$(git branch --show-current)" = "{SHIP_BRANCH}" ] || { echo "[bkit-ship] not on {SHIP_BRANCH} in {WORKTREE_PATH}" >&2; exit 1; }
208
- "{BKIT}" runtime row --workflow=ship --file="{STATUS}" >/dev/null || exit 1
209
- "{BKIT}" runtime assert --workflow=ship --file="{STATUS}" >/dev/null
210
- ```
211
- Update `BRANCH` = `SHIP_BRANCH`; carry `SHIP_BRANCH` to every later step.
212
- Create: `docs/plans/{YYYYMM}/logs/{FID}/ship-input-{RUN}.md` in `{WORKTREE_PATH}` = session prompt + `ISSUE_TEXT` + `docs/plans/{YYYYMM}/{FID}-plan.md` (if present).
213
- 3. **If** `BRANCH` does not contain `{FID}` **and** does not contain `{ISSUE_ID}` (case-insensitive) โ†’ emit `[bkit-ship] WARNING branch {BRANCH} not named for {FID} โ€” shipping it as named` โ†’ continue.
214
- 4. Find the branch's PR โ€” open first, then merged:
213
+ 1. Create: `docs/plans/{YYYYMM}/logs/{FID}/ship-input-{RUN}.md` in `{WORKTREE_PATH}` = session prompt + `ISSUE_TEXT` + `docs/plans/{YYYYMM}/{FID}-plan.md` (if present).
214
+ 2. **If** `BRANCH` does not contain `{FID}` **and** does not contain `{ISSUE_ID}` (case-insensitive) โ†’ emit `[bkit-ship] WARNING branch {BRANCH} not named for {FID} โ€” shipping it as named` โ†’ continue.
215
+ 3. Find the branch's PR โ€” open first, then merged:
215
216
  ```bash
216
217
  "{BKIT}" prs probe --head="{SHIP_BRANCH}" --state=all
217
218
  ```
218
219
  โ†’ hold `number` as `PR_NUMBER`, `baseRefName` as `PR_BASE`, `state`.
219
220
  **Route:**
220
221
  - **If** exit 0 **and** `PR_BASE` != dev โ†’ **Failure Path**.
221
- - **If** exit 0 โ†’ sub-step 5.
222
+ - **If** exit 0 โ†’ sub-step 4.
222
223
  - **If** exit 1 โ†’ open PR, `SHIP_OPENED_PR` = true, `docs/plans/{YYYYMM}/{FID}-plan.md` (if present):
223
224
  ```bash
224
225
  B=$(git branch --show-current)
@@ -234,24 +235,24 @@ description: "Ship Feature โ€” Autonomous merge and archive"
234
235
  ```
235
236
  **If** exit 80 โ†’ `create_pull_request` with the printed `title`, `body`, `base`, `head`. **If** any other non-zero exit โ†’ **Failure Path**. Re-run the `bkit prs probe` above โ†’ hold `number` as `PR_NUMBER`, `baseRefName` as `PR_BASE`, `state`. Assert `PR_NUMBER` non-empty and `PR_BASE` = dev. **Else** โ†’ **Failure Path**.
236
237
  - **Else** โ†’ **Failure Path**.
237
- 5. **Route:**
238
+ 4. **Route:**
238
239
  - **If** `state` = MERGED โ†’ record the resume marker โ†’ Step 13:
239
240
  ```bash
240
241
  "{BKIT}" status row --file="{STATUS}" --workflow=ship --type=ship-merged-on-entry >/dev/null
241
242
  ```
242
243
  - **Else** โ†’ next sub-step.
243
- 6. Read PR head SHA (`ENTRY_HEAD`) and mergeable state:
244
+ 5. Read PR head SHA (`ENTRY_HEAD`) and mergeable state:
244
245
  ```bash
245
246
  "{BKIT}" prs probe --number="{PR_NUMBER}"
246
247
  ```
247
248
  โ†’ hold `headRefOid` as `ENTRY_HEAD`, `mergeable` as `MERGEABLE`. Assert `ENTRY_HEAD` non-empty.
248
- 7. **If** `SHIP_OPENED_PR` = true โ†’ wait for CI on the new PR first:
249
+ 6. **If** `SHIP_OPENED_PR` = true โ†’ wait for CI on the new PR first:
249
250
  ```bash
250
251
  "{BKIT}" runs wait --pr="{PR_NUMBER}" --until=present --budget-s=120 || exit 1
251
252
  "{BKIT}" runs wait --pr="{PR_NUMBER}" --until=completed
252
253
  ```
253
254
  `"{BKIT}" prs checks --number={PR_NUMBER}` โ†’ assert `green` = true. **If** exit 4 (rollup unreadable), `total` = 0, or `green` = false โ†’ **Failure Path**.
254
- 8. Finish (bookkeeping to `$BOOK_ROOT`, no branch commit):
255
+ 7. Finish (bookkeeping to `$BOOK_ROOT`, no branch commit):
255
256
  ```bash
256
257
  "{BKIT}" steps done --workflow=ship --step=ship-worktree-setup --file="{STATUS}" --artifact="docs/plans/{YYYYMM}/logs/{FID}/ship-input-{RUN}.md" --commit=none >/dev/null || exit 1
257
258
  "{BKIT}" steps finish --workflow=ship --step=ship-regression-guard --file="{STATUS}" --verdict=PASS --commit=none --number=2 --title="Verify PR (Worktree Setup + Regression Guard)" --tree="{BRANCH}"
@@ -264,7 +265,7 @@ description: "Ship Feature โ€” Autonomous merge and archive"
264
265
  ```
265
266
 
266
267
  - [ ] Mechanical checks passed (`steps gate` exit 0: `ship-input-{RUN}.md`, step `ship-worktree-setup` recorded; `steps finish` exit 0: `ship-regression-guard`)
267
- - [ ] On `SHIP_BRANCH` (not `dev|main`), worktree created / resumed or adopted (no rebase โ€” Path A); naming warning emitted when not named for `FID` / `ISSUE_ID`
268
+ - [ ] Naming warning emitted when `SHIP_BRANCH` is not named for `FID` / `ISSUE_ID`
268
269
  - [ ] PR number non-empty (`PR_NUMBER`); `PR_BASE` = dev (opened by ship, `openedPr` row recorded, CI awaited โ€” when no PR existed)
269
270
  - [ ] Entry head and mergeable read (`ENTRY_HEAD`, `MERGEABLE`); no PR CI failures confirmed
270
271
 
@@ -564,53 +565,38 @@ description: "Ship Feature โ€” Autonomous merge and archive"
564
565
 
565
566
  ---
566
567
 
567
- ## ๐Ÿค– Step 13 โ€” Switch to Dev
568
+ ## ๐Ÿค– Step 13 โ€” Update Local Dev
568
569
 
569
570
  **Run only if** `state` = MERGED.
570
571
 
571
- 1. Switch to `dev` and bring it level with `origin/dev` under the dev lock when `RUNTIME_DEVPUSHES` = true, then finish:
572
+ 1. Fast-forward local `dev` to `origin/dev`, then finish:
572
573
  ```bash
573
- cd "{REPO_ROOT}" || exit 1
574
- "{BKIT}" branches switch --fid="{FID}" --dev-pushes="{RUNTIME_DEVPUSHES}" --worktrees="{RUNTIME_WORKTREES}" || exit 1
575
- "{BKIT}" steps finish --workflow=ship --step=ship-switch-to-dev --file="{STATUS}" --commit=none --number=13 --title="Switch to Dev" --tree=dev
574
+ "{BKIT}" branches sync-dev || exit 1
575
+ "{BKIT}" steps finish --workflow=ship --step=ship-switch-to-dev --file="{STATUS}" --commit=none --number=13 --title="Update Local Dev" --tree=dev
576
576
  ```
577
577
 
578
- ### ๐Ÿ”’ Gate 13 โ€” Switch to Dev
578
+ ### ๐Ÿ”’ Gate 13 โ€” Update Local Dev
579
579
 
580
- - [ ] On `dev`, level with `origin/dev` (`branches switch` exit 0)
580
+ - [ ] Local `dev` fast-forwarded to `origin/dev`, or its local-only commits logged (`branches sync-dev` exit 0)
581
581
  - [ ] Mechanical checks passed (`steps finish` exit 0: step `ship-switch-to-dev` recorded)
582
582
 
583
583
  ---
584
584
 
585
- ## ๐Ÿค– Step 14 โ€” Worktree Cleanup
586
-
587
- **Run only if** `state` = MERGED.
588
-
589
- 1. Remove the feature worktree (only one a workflow created), then delete the local and remote feature branch unless another worktree holds it; finish:
590
- ```bash
591
- "{BKIT}" worktrees remove --fid="{FID}" --branch="{SHIP_BRANCH}" || exit 1
592
- "{BKIT}" steps finish --workflow=ship --step=ship-worktree-cleanup --file="{STATUS}" --commit=none --number=14 --title="Worktree Cleanup"
593
- ```
594
-
595
- ### ๐Ÿ”’ Gate 14 โ€” Worktree Cleanup
596
-
597
- - [ ] Worktree removed (`.worktrees/{FID}`, or was already absent, or ownership marker absent โ†’ skipped) and pruned
598
- - [ ] Local and remote `{SHIP_BRANCH}` branch deleted or already absent (`branchDeleted`), or both kept and the holding worktree named (`branchBlockedBy`)
599
- - [ ] Mechanical checks passed (`steps finish` exit 0: step `ship-worktree-cleanup` recorded)
600
-
601
- ---
602
-
603
- ## ๐Ÿค– Step 15 โ€” Close Workflow
585
+ ## ๐Ÿค– Step 14 โ€” Close Workflow
604
586
 
605
587
  1. Assert the capstone passed at the squash commit, recording the squash-merge CI verdict (`ship-merge-ci`) before routing:
606
588
  ```bash
607
589
  "{BKIT}" runs gate --squash-of="{PR_NUMBER}" --repo="{OWNER_REPO}" --capstone-only --record="{STATUS}"
608
590
  ```
609
591
  โ†’ hold `head` as `{SQUASH_SHA}`.
610
- 2. Close under the dev lock โ€” on `dev` when `RUNTIME_DEVPUSHES` = true, else a detached `origin/dev` worktree in the outbox โ€” commit `docs({FID}): ship DONE bkit [skip ci]` (single path-scoped commit carrying the close step row and telemetry), release the workflow lock, then push `dev` (a refused push lands through a `ship-close/{FID}` PR):
592
+ 2. Close โ€” keep the summary in the outbox (the close removes the worktree it lives in), land `docs({FID}): ship DONE bkit [skip ci]` on `dev` (refused โ†’ `ship-close/{FID}` PR), release the lock, remove the worktree and `{SHIP_BRANCH}`, return to `{REPO_ROOT}`:
611
593
  ```bash
612
- "{BKIT}" workflows close --workflow=ship --fid="{FID}" --month="{YYYYMM}" --file="{STATUS}" --pr-number="{PR_NUMBER}" --squash-sha="{SQUASH_SHA}" --owner-repo="{OWNER_REPO}" --outbox="{OUTBOX}" --flush --token="{LOCK_TOKEN}" --dev-pushes --number=15 --title="Close Workflow"
594
+ rm -f "{OUTBOX}/ship-summary.md"
595
+ [ ! -f "docs/plans/{YYYYMM}/logs/{FID}/ship-summary.md" ] || cp "docs/plans/{YYYYMM}/logs/{FID}/ship-summary.md" "{OUTBOX}/ship-summary.md" || exit 1
596
+ "{BKIT}" workflows close --workflow=ship --fid="{FID}" --month="{YYYYMM}" --file="{STATUS}" --pr-number="{PR_NUMBER}" --squash-sha="{SQUASH_SHA}" --owner-repo="{OWNER_REPO}" --outbox="{OUTBOX}" --flush --token="{LOCK_TOKEN}" --branch="{SHIP_BRANCH}" --number=14 --title="Close Workflow"; rc=$?
597
+ cd "{REPO_ROOT}"; exit $rc
613
598
  ```
599
+ โ†’ hold `landed.via` as `{CLOSE_VIA}`.
614
600
  3. <!-- bkit:tracker true start -->
615
601
  Compute the label transition and board move:
616
602
  ```bash
@@ -630,29 +616,32 @@ description: "Ship Feature โ€” Autonomous merge and archive"
630
616
  "{BKIT}" tips --workflow=ship
631
617
  ```
632
618
  Plain text, not JSON. Hold stdout as `{BKIT_TIPS}`; prints nothing or exits non-zero โ†’ `{BKIT_TIPS}` empty.
633
- 5. Final return: Display `ship-summary.md` content verbatim as final message to user; do not summarise or trim; do not auto-invoke. **If** `ship-summary.md` absent โ†’ display `PR was already merged โ€” no ship summary this run.` **HARD STOP**.
619
+ 5. Final return: Display `{OUTBOX}/ship-summary.md` content verbatim as final message to user; do not summarise or trim; do not auto-invoke. **If** `{OUTBOX}/ship-summary.md` absent โ†’ display `PR was already merged โ€” no ship summary this run.` **HARD STOP**.
634
620
  <!-- bkit:tracker true start -->
635
621
  Append issue link [{ISSUE_ID} {TITLE}]({URL})
636
622
  <!-- bkit:tracker true end -->
623
+ Append `Would you like me to explain any of this in plain English? Then write 'yes, explain in plain english'.`
637
624
  Append `{BKIT_TIPS}` under a `## bkit Tips` heading, unless empty.
638
- Append as last line `Would you like me to explain this in plain English?`
639
625
  6. **If** user requests plain English explanation โ†’ restate the summary in plain English; name terms and say what they mean; identifiers stay verbatim; plainness lives in sentences, NOT nouns; do not re-run any step.
640
626
 
641
- ### ๐Ÿ”’ Gate 15 โ€” Close Workflow
627
+ ### ๐Ÿ”’ Gate 14 โ€” Close Workflow
642
628
 
643
629
  ```bash
644
- "{BKIT}" steps gate --file="{STATUS}" --workflow=ship --step=ship-close-workflow
630
+ "{BKIT}" steps gate --file="{REPO_ROOT}/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl" --ref=origin/dev --workflow=ship --step=ship-close-workflow
645
631
  ```
646
632
 
633
+ **If** `CLOSE_VIA` = close-pr-open โ†’ drop `--ref`, gate `--file="{STATUS}"`.
634
+
647
635
  - [ ] Squash-merge CI capstone green (`runs gate --squash-of --capstone-only` exit 0 at `SQUASH_SHA`; row `ship-merge-ci` with `verdict`, `reason`)
648
- - [ ] Close landed (`workflows close --flush` exit 0: `ship` `DONE`, close telemetry committed, single path-scoped `[skip ci]` close commit pushed to `dev` or published through `ship-close/{FID}`, lock released, close worktree removed)
649
- - [ ] Mechanical checks passed (`steps gate` exit 0: step `ship-close-workflow` recorded)
650
- - [ ] Logs retained at `docs/plans/{YYYYMM}/logs/{FID}/` for manual cleanup; worktree cleaned up
651
- - [ ] Final return displayed (`ship-summary.md` content verbatim)
636
+ - [ ] Close landed (`workflows close --flush` exit 0: `ship` `DONE`, close telemetry committed, single path-scoped `[skip ci]` close commit pushed to `dev` or published through `ship-close/{FID}`, lock released, throwaway checkout removed; a close that did not land keeps the lock and goes to the **Failure Path**)
637
+ - [ ] Worktree and `{SHIP_BRANCH}` removed, or kept with a reason; cwd = `{REPO_ROOT}` (`worktree.removed`, `worktree.branchDeleted`, `reason`, `branchBlockedBy`)
638
+ - [ ] Mechanical checks passed (`steps gate` exit 0: step `ship-close-workflow` recorded on `origin/dev`)
639
+ - [ ] Logs retained at `docs/plans/{YYYYMM}/logs/{FID}/` on `dev` for manual cleanup
640
+ - [ ] Final return displayed (`{OUTBOX}/ship-summary.md` content verbatim, copied before the close)
652
641
 
653
642
  <!-- bkit:tracker true start -->
654
643
 
655
644
  - [ ] Issue update attempted (phase label `bkit:merged`, status / state `In Review`; issue left open for human close)
656
- - [ ] Artifact link list and telemetry report embedded in `Step 15` comment
645
+ - [ ] Artifact link list and telemetry report embedded in `Step 14` comment
657
646
 
658
647
  <!-- bkit:tracker true end -->
@@ -22,18 +22,7 @@ per-repo) โ†’ fill the fields below โ†’ **Save**.
22
22
 
23
23
  @@CLOUD_NETWORK_ALLOWLIST@@
24
24
 
25
- ## 3 ยท Environment variables
26
-
27
- Paste into the **Environment variables** field (`.env` format, one `KEY=value`
28
- per line):
29
-
30
- ```dotenv
31
- @@CLOUD_ENV_VARS@@
32
- ```
33
-
34
- @@CLOUD_ENV_NOTES@@
35
-
36
- ## 4 ยท Setup script
25
+ ## 3 ยท Setup script
37
26
 
38
27
  Paste into the **Setup script** field. Runs once as root before the first
39
28
  session; the resulting filesystem is snapshotted and reused, so later sessions
@@ -118,6 +107,17 @@ Keep total runtime under ~5 minutes or the snapshot won't build. `pnpm install`
118
107
  and `vale sync` are **not** here โ€” they belong in `.claude/hooks/bkit-cloud-bootstrap.sh`
119
108
  (installed by `bkit install --auto=claude`) so they re-run on resumed sessions.
120
109
 
110
+ ## 4 ยท Environment variables
111
+
112
+ Paste into the **Environment variables** field (`.env` format, one `KEY=value`
113
+ per line):
114
+
115
+ ```dotenv
116
+ @@CLOUD_ENV_VARS@@
117
+ ```
118
+
119
+ @@CLOUD_ENV_NOTES@@
120
+
121
121
  ## 5 ยท Verify (first session)
122
122
 
123
123
  ```bash