@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.
- package/.bkit/README.md +3 -2
- package/.bkit/core/.agents/docs.md +1 -1
- package/.bkit/core/.agents/rules.md +8 -2
- package/.bkit/core/.bkit/README.md +2 -1
- package/.bkit/core/.bkit/cloud.md +33 -33
- package/.bkit/core/.bkit/comparison.md +1 -1
- package/.bkit/core/.bkit/install.md +6 -5
- package/.bkit/core/.bkit/lite.md +6 -6
- package/.bkit/core/.bkit/pipeline.md +4 -3
- package/.bkit/core/.bkit/prompts.md +4 -3
- package/.bkit/core/.bkit/providers.md +1 -1
- package/.bkit/core/.bkit/templates.md +35 -5
- package/.bkit/core/.bkit/trackers.md +7 -8
- package/.bkit/core/.bkit/workflows.md +106 -86
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
- package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/engine/checks/status-holes.ts +0 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +16 -0
- package/.bkit/core/engine/checks/tips/index.ts +49 -27
- package/.bkit/core/engine/cli.ts +22 -15
- package/.bkit/core/engine/commands/comply.ts +25 -16
- package/.bkit/core/engine/commands/install/install.ts +11 -4
- package/.bkit/core/engine/commands/land.ts +156 -0
- package/.bkit/core/engine/commands/lib.ts +10 -8
- package/.bkit/core/engine/commands/registry.ts +2 -0
- package/.bkit/core/engine/commands/tips.ts +7 -3
- package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
- package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
- package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
- package/.bkit/core/engine/commands/workflow/prs.ts +11 -2
- package/.bkit/core/engine/commands/workflow/roadmap.ts +48 -53
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
- package/.bkit/core/engine/commands/workflow/status.ts +33 -11
- package/.bkit/core/engine/commands/workflow/steps.ts +24 -15
- package/.bkit/core/engine/commands/workflow/workflows.ts +433 -265
- package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
- package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
- package/.bkit/core/engine/install/modules/core.ts +15 -0
- package/.bkit/core/engine/install/placeholders.ts +13 -17
- package/.bkit/core/engine/shared/settings.ts +8 -0
- package/.bkit/core/engine/shared/timeouts.ts +8 -7
- package/.bkit/core/prompts/bkit-audit-generate.md +47 -4
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +3 -3
- package/.bkit/core/workflows/bkit-auto.md +2 -2
- package/.bkit/core/workflows/bkit-build.md +7 -7
- package/.bkit/core/workflows/bkit-debug.md +11 -11
- package/.bkit/core/workflows/bkit-design.md +20 -11
- package/.bkit/core/workflows/bkit-plan.md +23 -13
- package/.bkit/core/workflows/bkit-ship.md +82 -93
- package/.bkit/shared/.claude/bkit-cloud.md +12 -12
- package/.bkit/shared/.claude/settings.json +1 -0
- package/.bkit/shared/docs/deployments.md +29 -25
- package/.bkit/shared/gitignore +1 -2
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
- package/.bkit/templates/.github/workflows/bkit-ci.yml +7 -2
- package/.bkit/templates/.husky/pre-commit +6 -0
- package/.bkit/templates/.husky/pre-push +7 -0
- package/.bkit/templates/.lintstagedrc.json +5 -1
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
- package/CHANGELOG.md +48 -0
- package/README.md +97 -96
- package/dist/checks/status-holes.js +0 -1
- package/dist/checks/tips/catalogue.js +14 -0
- package/dist/checks/tips/index.js +44 -28
- package/dist/cli.js +22 -16
- package/dist/commands/comply.js +20 -13
- package/dist/commands/install/install.js +10 -4
- package/dist/commands/land.js +129 -0
- package/dist/commands/lib.js +9 -6
- package/dist/commands/registry.js +2 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +300 -243
- package/dist/commands/workflow/disk.js +452 -0
- package/dist/commands/workflow/issues.js +63 -27
- package/dist/commands/workflow/locks.js +35 -130
- package/dist/commands/workflow/prs.js +5 -2
- package/dist/commands/workflow/roadmap.js +49 -56
- package/dist/commands/workflow/runtime.js +3 -2
- package/dist/commands/workflow/status.js +32 -12
- package/dist/commands/workflow/steps.js +18 -11
- package/dist/commands/workflow/workflows.js +388 -247
- package/dist/commands/workflow/workstreams.js +3 -2
- package/dist/commands/workflow/worktrees.js +11 -1
- package/dist/install/modules/core.js +13 -0
- package/dist/install/placeholders.js +13 -19
- package/dist/shared/settings.js +5 -0
- package/dist/shared/timeouts.js +8 -7
- 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.
|
|
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.
|
|
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)
|
|
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)
|
|
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
|
|
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. **
|
|
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` โ
|
|
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 `
|
|
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.
|
|
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.
|
|
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)
|
|
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)
|
|
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
|
|
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. **
|
|
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
|
|
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/
|
|
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` โ
|
|
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 `
|
|
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.
|
|
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 `$
|
|
25
|
-
> - **Status branch:**
|
|
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)
|
|
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)
|
|
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} --
|
|
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.
|
|
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 --
|
|
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 `
|
|
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}"
|
|
137
|
+
"{BKIT}" locks acquire --kind=workflow --workflow=ship --fid="{FID}"
|
|
138
138
|
```
|
|
139
139
|
โ hold `token` as `{LOCK_TOKEN}`, `month` as `{YYYYMM}`.
|
|
140
|
-
7.
|
|
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
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
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 --
|
|
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
|
|
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
|
-
- [ ]
|
|
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.
|
|
200
|
-
|
|
201
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
- [ ]
|
|
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 โ
|
|
568
|
+
## ๐ค Step 13 โ Update Local Dev
|
|
568
569
|
|
|
569
570
|
**Run only if** `state` = MERGED.
|
|
570
571
|
|
|
571
|
-
1.
|
|
572
|
+
1. Fast-forward local `dev` to `origin/dev`, then finish:
|
|
572
573
|
```bash
|
|
573
|
-
|
|
574
|
-
"{BKIT}"
|
|
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 โ
|
|
578
|
+
### ๐ Gate 13 โ Update Local Dev
|
|
579
579
|
|
|
580
|
-
- [ ]
|
|
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 โ
|
|
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
|
|
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
|
-
|
|
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
|
|
627
|
+
### ๐ Gate 14 โ Close Workflow
|
|
642
628
|
|
|
643
629
|
```bash
|
|
644
|
-
"{BKIT}" steps gate --file="{
|
|
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
|
|
649
|
-
- [ ]
|
|
650
|
-
- [ ]
|
|
651
|
-
- [ ]
|
|
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
|
|
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 ยท
|
|
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
|