@cbartens/bkit 5.2.4 → 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 +27 -11
- package/.bkit/core/.agents/context.md +1 -1
- package/.bkit/core/.agents/docs.md +1 -1
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +1 -1
- package/.bkit/core/.agents/rules.md +18 -1
- package/.bkit/core/.bkit/README.md +26 -10
- package/.bkit/core/.bkit/cloud.md +40 -39
- package/.bkit/core/.bkit/comparison.md +68 -345
- package/.bkit/core/.bkit/install.md +16 -9
- package/.bkit/core/.bkit/lite.md +73 -0
- package/.bkit/core/.bkit/pipeline.md +346 -0
- package/.bkit/core/.bkit/prompts.md +90 -74
- package/.bkit/core/.bkit/providers.md +42 -23
- package/.bkit/core/.bkit/templates.md +138 -19
- package/.bkit/core/.bkit/trackers.md +49 -4
- package/.bkit/core/.bkit/workflows.md +144 -123
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +1 -1
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +7 -4
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -5
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
- 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 +26 -21
- 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 +22 -15
- 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 +7 -7
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +12 -9
- 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 +14 -12
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +10 -8
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/docs/templates/bkit-plan.md +8 -6
- package/.bkit/core/engine/checks/after/auth.ts +9 -9
- package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
- package/.bkit/core/engine/checks/after/github.ts +29 -120
- package/.bkit/core/engine/checks/after/index.ts +2 -2
- package/.bkit/core/engine/checks/after/managed.ts +8 -28
- package/.bkit/core/engine/checks/after/tools.ts +3 -15
- package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
- package/.bkit/core/engine/checks/before/index.ts +7 -43
- package/.bkit/core/engine/checks/before/mcp.ts +17 -8
- package/.bkit/core/engine/checks/before/repo.ts +9 -12
- package/.bkit/core/engine/checks/status-holes.ts +4 -6
- package/.bkit/core/engine/checks/tips/catalogue.ts +76 -24
- package/.bkit/core/engine/checks/tips/detect.ts +45 -2
- package/.bkit/core/engine/checks/tips/index.ts +77 -26
- package/.bkit/core/engine/cli.ts +57 -27
- package/.bkit/core/engine/commands/analysis.ts +36 -26
- package/.bkit/core/engine/commands/comply.ts +42 -32
- package/.bkit/core/engine/commands/harvest.ts +12 -12
- package/.bkit/core/engine/commands/install/doctor.ts +57 -28
- package/.bkit/core/engine/commands/install/install.ts +73 -130
- package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
- package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
- package/.bkit/core/engine/commands/land.ts +156 -0
- package/.bkit/core/engine/commands/lib.ts +45 -18
- package/.bkit/core/engine/commands/registry.ts +2 -0
- package/.bkit/core/engine/commands/tips.ts +12 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +386 -286
- package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
- package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
- package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
- package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
- package/.bkit/core/engine/commands/workflow/prs.ts +15 -4
- package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
- package/.bkit/core/engine/commands/workflow/roadmap.ts +49 -53
- package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
- 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 +25 -15
- package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
- package/.bkit/core/engine/commands/workflow/workflows.ts +436 -267
- package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -2
- package/.bkit/core/engine/commands/workflow/worktrees.ts +24 -6
- package/.bkit/core/engine/install/cloud-env.ts +10 -31
- package/.bkit/core/engine/install/manifest.ts +14 -7
- package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
- package/.bkit/core/engine/install/modules/claude.ts +20 -28
- package/.bkit/core/engine/install/modules/cloud.ts +5 -2
- package/.bkit/core/engine/install/modules/codex.ts +15 -29
- package/.bkit/core/engine/install/modules/core.ts +106 -70
- package/.bkit/core/engine/install/modules/cursor.ts +6 -20
- package/.bkit/core/engine/install/modules/index.ts +7 -1
- package/.bkit/core/engine/install/modules/opencode.ts +48 -70
- package/.bkit/core/engine/install/network-allowlist.ts +73 -0
- package/.bkit/core/engine/install/placeholders.ts +16 -35
- package/.bkit/core/engine/install/write.ts +59 -12
- package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
- package/.bkit/core/engine/render/hosts.ts +47 -67
- package/.bkit/core/engine/render/models.ts +29 -11
- package/.bkit/core/engine/shared/branches.ts +13 -0
- package/.bkit/core/engine/shared/egress.ts +3 -3
- package/.bkit/core/engine/shared/json.ts +18 -1
- package/.bkit/core/engine/shared/package-json.ts +63 -0
- package/.bkit/core/engine/shared/package-roots.ts +0 -10
- package/.bkit/core/engine/shared/protected-paths.ts +5 -130
- package/.bkit/core/engine/shared/settings.ts +44 -0
- package/.bkit/core/engine/shared/timeouts.ts +8 -7
- package/.bkit/core/hooks/antigravity-hook.js +1 -0
- package/.bkit/core/hooks/guardrails-shell.js +186 -40
- package/.bkit/core/hooks/guardrails-tiers.js +5 -78
- package/.bkit/core/prompts/bkit-audit-generate.md +103 -7
- package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
- package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
- package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
- package/.bkit/core/prompts/bkit-design-spike.md +1 -1
- package/.bkit/core/prompts/bkit-design-summary.md +2 -2
- package/.bkit/core/prompts/bkit-design-update.md +1 -1
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
- package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
- package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
- package/.bkit/core/prompts/bkit-plan-update.md +1 -1
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
- package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
- package/.bkit/core/workflows/bkit-auto.md +2 -2
- package/.bkit/core/workflows/bkit-build.md +10 -10
- package/.bkit/core/workflows/bkit-debug.md +80 -44
- package/.bkit/core/workflows/bkit-design.md +22 -13
- package/.bkit/core/workflows/bkit-plan.md +33 -16
- package/.bkit/core/workflows/bkit-ship.md +87 -98
- package/.bkit/shared/.claude/bkit-cloud.md +58 -25
- package/.bkit/shared/.claude/settings.json +19 -0
- package/.bkit/shared/.cursor/mcp.json +2 -1
- package/.bkit/shared/.opencode/opencode.json +19 -1
- package/.bkit/shared/docs/deployments.md +49 -29
- package/.bkit/shared/docs/security.md +8 -6
- package/.bkit/shared/docs/testing.md +9 -5
- package/.bkit/shared/gitignore +1 -2
- package/.bkit/templates/.cursor/Dockerfile +30 -16
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
- package/.bkit/templates/.github/renovate.json5 +91 -12
- package/.bkit/templates/.github/workflows/bkit-ci.yml +73 -55
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
- package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
- package/.bkit/templates/.husky/pre-commit +6 -0
- package/.bkit/templates/.husky/pre-push +15 -3
- package/.bkit/templates/.lintstagedrc.json +5 -1
- package/.bkit/templates/.oxlintrc.json +21 -0
- package/.bkit/templates/docs/capabilities.md +1 -1
- package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
- package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
- package/CHANGELOG.md +98 -3
- package/README.md +252 -122
- package/dist/checks/after/auth.js +10 -11
- package/dist/checks/after/ci-yml.js +11 -14
- package/dist/checks/after/github.js +32 -125
- package/dist/checks/after/index.js +3 -2
- package/dist/checks/after/managed.js +8 -24
- package/dist/checks/after/tools.js +3 -16
- package/dist/checks/before/context-fetch.js +1 -21
- package/dist/checks/before/index.js +6 -42
- package/dist/checks/before/mcp.js +14 -9
- package/dist/checks/before/repo.js +8 -11
- package/dist/checks/status-holes.js +5 -7
- package/dist/checks/tips/catalogue.js +65 -18
- package/dist/checks/tips/detect.js +41 -2
- package/dist/checks/tips/index.js +61 -25
- package/dist/cli.js +52 -26
- package/dist/commands/analysis.js +21 -5
- package/dist/commands/comply.js +40 -31
- package/dist/commands/harvest.js +12 -13
- package/dist/commands/install/doctor.js +55 -23
- package/dist/commands/install/install.js +72 -122
- package/dist/commands/install/uninstall.js +165 -31
- package/dist/commands/install/upgrade.js +46 -39
- package/dist/commands/land.js +129 -0
- package/dist/commands/lib.js +41 -16
- package/dist/commands/registry.js +2 -0
- package/dist/commands/tips.js +10 -3
- package/dist/commands/workflow/branches.js +303 -248
- package/dist/commands/workflow/counters.js +17 -7
- package/dist/commands/workflow/disk.js +452 -0
- package/dist/commands/workflow/fids.js +39 -0
- package/dist/commands/workflow/issues.js +63 -27
- package/dist/commands/workflow/ledgers.js +3 -1
- package/dist/commands/workflow/locks.js +35 -130
- package/dist/commands/workflow/prs.js +8 -5
- package/dist/commands/workflow/repo.js +2 -2
- package/dist/commands/workflow/roadmap.js +50 -57
- package/dist/commands/workflow/runs.js +5 -5
- package/dist/commands/workflow/runtime.js +3 -2
- package/dist/commands/workflow/status.js +32 -12
- package/dist/commands/workflow/steps.js +19 -11
- package/dist/commands/workflow/tests.js +16 -3
- package/dist/commands/workflow/workflows.js +390 -249
- package/dist/commands/workflow/workstreams.js +4 -2
- package/dist/commands/workflow/worktrees.js +15 -6
- package/dist/install/cloud-env.js +10 -23
- package/dist/install/manifest.js +14 -7
- package/dist/install/modules/antigravity.js +15 -26
- package/dist/install/modules/claude.js +17 -21
- package/dist/install/modules/cloud.js +6 -2
- package/dist/install/modules/codex.js +15 -29
- package/dist/install/modules/core.js +95 -63
- package/dist/install/modules/cursor.js +6 -9
- package/dist/install/modules/index.js +6 -1
- package/dist/install/modules/opencode.js +41 -72
- package/dist/install/network-allowlist.js +62 -0
- package/dist/install/placeholders.js +16 -35
- package/dist/install/write.js +55 -15
- package/dist/ledgers/telemetry.js +5 -4
- package/dist/render/hosts.js +30 -55
- package/dist/render/models.js +20 -9
- package/dist/shared/branches.js +11 -0
- package/dist/shared/egress.js +0 -2
- package/dist/shared/json.js +14 -0
- package/dist/shared/package-json.js +61 -0
- package/dist/shared/package-roots.js +0 -8
- package/dist/shared/protected-paths.js +5 -122
- package/dist/shared/settings.js +23 -1
- package/dist/shared/timeouts.js +8 -7
- package/package.json +21 -17
- package/.bkit/core/.agents/shortcuts.md +0 -73
|
@@ -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
|
|
|
@@ -293,7 +294,7 @@ description: "Ship Feature — Autonomous merge and archive"
|
|
|
293
294
|
|
|
294
295
|
## 🧠 Step 4 — Integrate (Path B only)
|
|
295
296
|
|
|
296
|
-
**Run only if** `BASE_PATH` = B.
|
|
297
|
+
**Run only if** `BASE_PATH` = B.
|
|
297
298
|
|
|
298
299
|
1. **If** `MERGEABLE` = MERGEABLE (B1 — no textual conflict): refresh the PR head server-side → Step 5:
|
|
299
300
|
```bash
|
|
@@ -540,7 +541,7 @@ description: "Ship Feature — Autonomous merge and archive"
|
|
|
540
541
|
|
|
541
542
|
## 🧠 Step 12 — Failure Remediate
|
|
542
543
|
|
|
543
|
-
**Run only if** `state` != MERGED.
|
|
544
|
+
**Run only if** `state` != MERGED.
|
|
544
545
|
|
|
545
546
|
1. Derive the next strategy rung from `{STATUS}`:
|
|
546
547
|
```bash
|
|
@@ -555,7 +556,7 @@ description: "Ship Feature — Autonomous merge and archive"
|
|
|
555
556
|
```bash
|
|
556
557
|
"{BKIT}" steps finish --workflow=ship --step=ship-failure-remediate --file="{STATUS}" --attempt-of=ship-merge-pr:current --agent=bkit-debug-failure-remediate --artifact="docs/plans/{YYYYMM}/logs/{FID}/ship-failure-remediate-<attempt>-log.md" --commit=none --number=12 --title="Failure Remediate"
|
|
557
558
|
```
|
|
558
|
-
4. **If** `verdict` = PASS → Step 10 (re-run merge). **Else** → **Failure Path
|
|
559
|
+
4. **If** `verdict` = PASS → Step 10 (re-run merge). **Else** → **Failure Path**.
|
|
559
560
|
|
|
560
561
|
### 🔒 Gate 12 — Failure Remediate
|
|
561
562
|
|
|
@@ -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
|
|
@@ -629,30 +615,33 @@ description: "Ship Feature — Autonomous merge and archive"
|
|
|
629
615
|
```bash
|
|
630
616
|
"{BKIT}" tips --workflow=ship
|
|
631
617
|
```
|
|
632
|
-
Plain text, not JSON. Hold stdout as `{
|
|
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**.
|
|
618
|
+
Plain text, not JSON. Hold stdout as `{BKIT_TIPS}`; prints nothing or exits non-zero → `{BKIT_TIPS}` empty.
|
|
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 -->
|
|
637
|
-
Append `
|
|
638
|
-
Append
|
|
623
|
+
Append `Would you like me to explain any of this in plain English? Then write 'yes, explain in plain english'.`
|
|
624
|
+
Append `{BKIT_TIPS}` under a `## bkit Tips` heading, unless empty.
|
|
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
|
|
@@ -44,33 +33,63 @@ start fast.
|
|
|
44
33
|
@@CLOUD_CACHE_BUST@@
|
|
45
34
|
set -euo pipefail
|
|
46
35
|
|
|
36
|
+
# Every download is pinned to a version and checked against its published sha256
|
|
37
|
+
# before it is unpacked or made executable. The image targets linux/amd64.
|
|
38
|
+
# Node — nodejs.org tarball checked against SHASUMS256.txt (linux-x64), same pin as
|
|
39
|
+
# `.bkit/templates/.cursor/Dockerfile`. bkit needs Node >=24 and the base image ships
|
|
40
|
+
# older majors, so this one goes into /usr/local and leads PATH for every step below.
|
|
41
|
+
# renovate: datasource=node-version depName=node
|
|
42
|
+
NODE_VERSION="24.21.0"
|
|
43
|
+
NODE_SHA256="fd8e59d5a511510f6a298afb548f18c7d2b1be404d8b4a27d94fbe49f56cb2d6"
|
|
44
|
+
if [ "$(/usr/local/bin/node --version 2>/dev/null || true)" != "v${NODE_VERSION}" ]; then
|
|
45
|
+
command -v xz >/dev/null 2>&1 || { apt-get update && apt-get install -y --no-install-recommends xz-utils; }
|
|
46
|
+
cd /tmp
|
|
47
|
+
curl -fsSLO --retry 3 --retry-all-errors "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
|
|
48
|
+
echo "${NODE_SHA256} node-v${NODE_VERSION}-linux-x64.tar.xz" | sha256sum -c -
|
|
49
|
+
tar -xJf "node-v${NODE_VERSION}-linux-x64.tar.xz" -C /usr/local --strip-components=1
|
|
50
|
+
rm -f "node-v${NODE_VERSION}-linux-x64.tar.xz"
|
|
51
|
+
fi
|
|
52
|
+
export PATH="/usr/local/bin:$PATH"
|
|
53
|
+
hash -r
|
|
54
|
+
|
|
55
|
+
# renovate: datasource=github-releases depName=errata-ai/vale
|
|
47
56
|
VALE_VERSION="3.9.1"
|
|
57
|
+
VALE_SHA256="fbc2eb47d0b8c50220ed1a2c5c611fbe0904ed567d638143d482016a18fd2db0"
|
|
48
58
|
if ! command -v vale >/dev/null 2>&1; then
|
|
49
59
|
cd /tmp
|
|
50
60
|
curl -fsSLO --retry 3 --retry-all-errors "https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz"
|
|
61
|
+
echo "${VALE_SHA256} vale_${VALE_VERSION}_Linux_64-bit.tar.gz" | sha256sum -c -
|
|
51
62
|
tar -xzf "vale_${VALE_VERSION}_Linux_64-bit.tar.gz" -C /usr/local/bin vale
|
|
52
63
|
chmod +x /usr/local/bin/vale
|
|
53
64
|
fi
|
|
54
65
|
|
|
66
|
+
# renovate: datasource=github-releases depName=cli/cli
|
|
67
|
+
GH_VERSION="2.102.0"
|
|
68
|
+
GH_SHA256="bb766f710eef8ede859c18578c72c327597cd4c8a85b06001b1f3843c6019386"
|
|
55
69
|
if ! command -v gh >/dev/null 2>&1; then
|
|
56
70
|
cd /tmp
|
|
57
|
-
#
|
|
58
|
-
#
|
|
59
|
-
#
|
|
60
|
-
# the base image's apt repos; `apt install gh` is not (gh isn't in default repos).
|
|
61
|
-
GH_VERSION=$(curl -fsSL -o /dev/null -w '%{url_effective}' "https://github.com/cli/cli/releases/latest" | sed -E 's#.*/tag/v##')
|
|
71
|
+
# Pinned release tarball from github.com (same host + install style as vale above),
|
|
72
|
+
# checked against the release's checksums.txt. Reliable regardless of the base
|
|
73
|
+
# image's apt repos; `apt install gh` is not (gh isn't in default repos).
|
|
62
74
|
curl -fsSLO --retry 3 --retry-all-errors "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_linux_amd64.tar.gz"
|
|
75
|
+
echo "${GH_SHA256} gh_${GH_VERSION}_linux_amd64.tar.gz" | sha256sum -c -
|
|
63
76
|
tar -xzf "gh_${GH_VERSION}_linux_amd64.tar.gz" -C /usr/local/bin --strip-components=2 "gh_${GH_VERSION}_linux_amd64/bin/gh"
|
|
64
77
|
chmod +x /usr/local/bin/gh
|
|
65
78
|
fi
|
|
66
79
|
|
|
80
|
+
# renovate: datasource=github-releases depName=jqlang/jq extractVersion=^jq-(?<version>.+)$
|
|
81
|
+
JQ_VERSION="1.7.1"
|
|
82
|
+
JQ_SHA256="5942c9b0934e510ee61eb3e30273f1b3fe2590df93933a93d7c58b81d19c8ff5"
|
|
67
83
|
if ! command -v jq >/dev/null 2>&1; then
|
|
68
|
-
# jq is a single static binary —
|
|
69
|
-
# host
|
|
70
|
-
# .bkit/templates/context/ ones,
|
|
71
|
-
# present; the base image may not ship it.
|
|
72
|
-
|
|
73
|
-
|
|
84
|
+
# jq is a single static binary — fetched from the jqlang release (same github.com
|
|
85
|
+
# host as vale/gh above) and checked against the release's sha256sum.txt before it is
|
|
86
|
+
# installed. context-fetch blocks, including the .bkit/templates/context/ ones,
|
|
87
|
+
# pipe their output through `| jq …` and assume it is present; the base image may not ship it.
|
|
88
|
+
cd /tmp
|
|
89
|
+
curl -fsSLO --retry 3 --retry-all-errors "https://github.com/jqlang/jq/releases/download/jq-${JQ_VERSION}/jq-linux-amd64"
|
|
90
|
+
echo "${JQ_SHA256} jq-linux-amd64" | sha256sum -c -
|
|
91
|
+
install -m 0755 jq-linux-amd64 /usr/local/bin/jq
|
|
92
|
+
rm -f jq-linux-amd64
|
|
74
93
|
fi
|
|
75
94
|
|
|
76
95
|
@@CLOUD_WORKSPACE_TRUST@@
|
|
@@ -81,19 +100,33 @@ fi
|
|
|
81
100
|
|
|
82
101
|
@@CLOUD_CONTEXT_FETCH_PROVISION@@
|
|
83
102
|
|
|
84
|
-
echo "cloud env ready: $(vale --version), $(gh --version | head -1), jq $(jq --version), pnpm $(pnpm -v)"
|
|
103
|
+
echo "cloud env ready: node $(node --version), $(vale --version), $(gh --version | head -1), jq $(jq --version), pnpm $(pnpm -v)"
|
|
85
104
|
```
|
|
86
105
|
|
|
87
106
|
Keep total runtime under ~5 minutes or the snapshot won't build. `pnpm install`
|
|
88
107
|
and `vale sync` are **not** here — they belong in `.claude/hooks/bkit-cloud-bootstrap.sh`
|
|
89
108
|
(installed by `bkit install --auto=claude`) so they re-run on resumed sessions.
|
|
90
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
|
+
|
|
91
121
|
## 5 · Verify (first session)
|
|
92
122
|
|
|
93
123
|
```bash
|
|
94
|
-
vale --version && gh --version && jq --version && pnpm -v
|
|
124
|
+
node --version && vale --version && gh --version && jq --version && pnpm -v
|
|
95
125
|
```
|
|
96
126
|
|
|
127
|
+
`node --version` must print `v24.21.0`. An older version means the session `PATH`
|
|
128
|
+
puts the image's own Node ahead of `/usr/local/bin`.
|
|
129
|
+
|
|
97
130
|
Then confirm workspace trust. Unset, Claude Code ignores every `permissions.allow`
|
|
98
131
|
row in `.claude/settings.json` and reports it on stderr only, where no cloud
|
|
99
132
|
session shows it:
|
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
"Bash(*)",
|
|
7
7
|
"mcp__github__*",
|
|
8
8
|
"mcp__claude_ai_Linear__*",
|
|
9
|
+
"mcp__linear__*",
|
|
9
10
|
"WebSearch",
|
|
10
11
|
"Bash(git push --force-with-lease:*)",
|
|
11
12
|
"Read(./.env.example)",
|
|
@@ -25,6 +26,24 @@
|
|
|
25
26
|
"Bash(git push * --force *)",
|
|
26
27
|
"Bash(git push * -f*)",
|
|
27
28
|
"Bash(git push * +*)",
|
|
29
|
+
"Bash(git -* push* --force)",
|
|
30
|
+
"Bash(git -* push* --force *)",
|
|
31
|
+
"Bash(git -* push* -f*)",
|
|
32
|
+
"Bash(git -* push* +*)",
|
|
33
|
+
"Bash(git push* -uf*)",
|
|
34
|
+
"Bash(git -* push* -uf*)",
|
|
35
|
+
"Bash(git push* -vf*)",
|
|
36
|
+
"Bash(git -* push* -vf*)",
|
|
37
|
+
"Bash(git push* -qf*)",
|
|
38
|
+
"Bash(git -* push* -qf*)",
|
|
39
|
+
"Bash(git push* -nf*)",
|
|
40
|
+
"Bash(git -* push* -nf*)",
|
|
41
|
+
"Bash(git push* -df*)",
|
|
42
|
+
"Bash(git -* push* -df*)",
|
|
43
|
+
"Bash(git push* -4f*)",
|
|
44
|
+
"Bash(git -* push* -4f*)",
|
|
45
|
+
"Bash(git push* -6f*)",
|
|
46
|
+
"Bash(git -* push* -6f*)",
|
|
28
47
|
"Read(./**/*.pem)",
|
|
29
48
|
"Read(./**/*.p12)",
|
|
30
49
|
"Read(./**/id_rsa)"
|
|
@@ -8,7 +8,8 @@
|
|
|
8
8
|
"type": "http",
|
|
9
9
|
"url": "https://api.githubcopilot.com/mcp/",
|
|
10
10
|
"headers": {
|
|
11
|
-
"Authorization": "Bearer ${BKIT_GH_TOKEN}"
|
|
11
|
+
"Authorization": "Bearer ${BKIT_GH_TOKEN}",
|
|
12
|
+
"X-MCP-Toolsets": "context,issues,pull_requests,repos,users,projects,actions"
|
|
12
13
|
}
|
|
13
14
|
}
|
|
14
15
|
}
|
|
@@ -64,7 +64,25 @@
|
|
|
64
64
|
"git push * --force": "deny",
|
|
65
65
|
"git push * --force *": "deny",
|
|
66
66
|
"git push * -f*": "deny",
|
|
67
|
-
"git push * +*": "deny"
|
|
67
|
+
"git push * +*": "deny",
|
|
68
|
+
"git -* push* --force": "deny",
|
|
69
|
+
"git -* push* --force *": "deny",
|
|
70
|
+
"git -* push* -f*": "deny",
|
|
71
|
+
"git -* push* +*": "deny",
|
|
72
|
+
"git push* -uf*": "deny",
|
|
73
|
+
"git -* push* -uf*": "deny",
|
|
74
|
+
"git push* -vf*": "deny",
|
|
75
|
+
"git -* push* -vf*": "deny",
|
|
76
|
+
"git push* -qf*": "deny",
|
|
77
|
+
"git -* push* -qf*": "deny",
|
|
78
|
+
"git push* -nf*": "deny",
|
|
79
|
+
"git -* push* -nf*": "deny",
|
|
80
|
+
"git push* -df*": "deny",
|
|
81
|
+
"git -* push* -df*": "deny",
|
|
82
|
+
"git push* -4f*": "deny",
|
|
83
|
+
"git -* push* -4f*": "deny",
|
|
84
|
+
"git push* -6f*": "deny",
|
|
85
|
+
"git -* push* -6f*": "deny"
|
|
68
86
|
}
|
|
69
87
|
},
|
|
70
88
|
"mcp": {
|