@cbartens/bkit 5.4.0 → 5.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/.bkit/README.md +19 -7
  2. package/.bkit/core/.agents/rules.md +24 -9
  3. package/.bkit/core/.bkit/README.md +18 -6
  4. package/.bkit/core/.bkit/cloud.md +46 -15
  5. package/.bkit/core/.bkit/comparison.md +2 -2
  6. package/.bkit/core/.bkit/install.md +19 -18
  7. package/.bkit/core/.bkit/pipeline.md +3 -1
  8. package/.bkit/core/.bkit/prompts.md +38 -20
  9. package/.bkit/core/.bkit/providers.md +6 -6
  10. package/.bkit/core/.bkit/templates.md +44 -13
  11. package/.bkit/core/.bkit/trackers.md +99 -35
  12. package/.bkit/core/.bkit/workflows.md +50 -45
  13. package/.bkit/core/AGENTS.md +2 -2
  14. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  15. package/.bkit/core/docs/templates/bkit-audit-issues.md +22 -6
  16. package/.bkit/core/engine/checks/after/auth.ts +88 -45
  17. package/.bkit/core/engine/checks/after/ci-yml.ts +0 -1
  18. package/.bkit/core/engine/checks/after/github.ts +42 -78
  19. package/.bkit/core/engine/checks/after/index.ts +1 -6
  20. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  21. package/.bkit/core/engine/checks/before/env.ts +28 -18
  22. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  23. package/.bkit/core/engine/checks/tips/catalogue.ts +15 -2
  24. package/.bkit/core/engine/checks/tips/index.ts +5 -2
  25. package/.bkit/core/engine/cli.ts +7 -5
  26. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  27. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  28. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  29. package/.bkit/core/engine/commands/workflow/issues.ts +61 -63
  30. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  31. package/.bkit/core/engine/commands/workflow/prs.ts +3 -1
  32. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  33. package/.bkit/core/engine/commands/workflow/roadmap.ts +5 -1
  34. package/.bkit/core/engine/commands/workflow/steps.ts +2 -2
  35. package/.bkit/core/engine/commands/workflow/workflows.ts +9 -4
  36. package/.bkit/core/engine/commands/workflow/worktrees.ts +91 -14
  37. package/.bkit/core/engine/install/manifest.ts +31 -10
  38. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  39. package/.bkit/core/engine/install/modules/core.ts +153 -4
  40. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  41. package/.bkit/core/engine/install/write.ts +37 -1
  42. package/.bkit/core/engine/render/trackers.ts +35 -23
  43. package/.bkit/core/engine/shared/egress.ts +6 -0
  44. package/.bkit/core/engine/shared/settings.ts +130 -11
  45. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  46. package/.bkit/core/prompts/bkit-audit-generate.md +42 -12
  47. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  48. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  49. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  50. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  51. package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -0
  52. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  53. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  54. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  55. package/.bkit/core/prompts/bkit-design-generate.md +4 -1
  56. package/.bkit/core/prompts/bkit-plan-generate.md +5 -3
  57. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  58. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  59. package/.bkit/core/prompts/bkit-utility-update-decisions.md +3 -1
  60. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +3 -1
  61. package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
  62. package/.bkit/core/prompts/bkit-utility-update-failures.md +3 -1
  63. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +3 -1
  64. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +9 -2
  65. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  66. package/.bkit/core/workflows/bkit-auto.md +19 -6
  67. package/.bkit/core/workflows/bkit-build.md +59 -17
  68. package/.bkit/core/workflows/bkit-debug.md +64 -20
  69. package/.bkit/core/workflows/bkit-design.md +83 -28
  70. package/.bkit/core/workflows/bkit-plan.md +61 -20
  71. package/.bkit/core/workflows/bkit-ship.md +48 -18
  72. package/.bkit/shared/.bkit/.env.example +8 -0
  73. package/.bkit/shared/.claude/settings.json +3 -1
  74. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  75. package/.bkit/shared/.cursor/mcp.json +11 -4
  76. package/.bkit/shared/.mcp.json +11 -4
  77. package/.bkit/shared/.opencode/opencode.json +2 -0
  78. package/.bkit/shared/docs/deployments.md +6 -7
  79. package/.bkit/shared/docs/security.md +1 -1
  80. package/.bkit/shared/docs/testing.md +13 -5
  81. package/.bkit/templates/.github/renovate.json5 +1 -1
  82. package/.bkit/templates/.github/workflows/bkit-ci.yml +21 -115
  83. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  84. package/.bkit/templates/.husky/pre-commit +4 -4
  85. package/.bkit/templates/.husky/pre-push +107 -18
  86. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  87. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  88. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  89. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  90. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  91. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  92. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  93. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  94. package/CHANGELOG.md +67 -1
  95. package/README.md +16 -6
  96. package/dist/checks/after/auth.js +81 -45
  97. package/dist/checks/after/ci-yml.js +0 -1
  98. package/dist/checks/after/github.js +41 -76
  99. package/dist/checks/after/index.js +2 -7
  100. package/dist/checks/after/tools.js +1 -1
  101. package/dist/checks/before/env.js +24 -17
  102. package/dist/checks/before/mcp.js +4 -2
  103. package/dist/checks/tips/catalogue.js +14 -2
  104. package/dist/checks/tips/index.js +4 -2
  105. package/dist/cli.js +7 -5
  106. package/dist/commands/ci/ci.js +100 -0
  107. package/dist/commands/install/uninstall.js +42 -0
  108. package/dist/commands/workflow/fids.js +22 -15
  109. package/dist/commands/workflow/issues.js +53 -61
  110. package/dist/commands/workflow/ledgers.js +26 -11
  111. package/dist/commands/workflow/prs.js +3 -1
  112. package/dist/commands/workflow/repo.js +6 -0
  113. package/dist/commands/workflow/roadmap.js +3 -1
  114. package/dist/commands/workflow/steps.js +2 -2
  115. package/dist/commands/workflow/workflows.js +9 -4
  116. package/dist/commands/workflow/worktrees.js +74 -13
  117. package/dist/install/manifest.js +30 -10
  118. package/dist/install/modules/cloud.js +3 -1
  119. package/dist/install/modules/core.js +157 -5
  120. package/dist/install/modules/opencode.js +6 -0
  121. package/dist/install/write.js +26 -2
  122. package/dist/render/trackers.js +34 -20
  123. package/dist/shared/egress.js +6 -0
  124. package/dist/shared/settings.js +59 -7
  125. package/package.json +14 -3
@@ -12,7 +12,7 @@
12
12
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
13
13
  > - Ships to consumers: describe the current setup only. NEVER an internal identifier (tracker issue number, ledger key, review-finding id) and NEVER project history — decisions belong in `docs/decisions.jsonl`, incidents in `docs/knowledge.jsonl`.
14
14
  > - Subagents are leaves, never invoke other subagents.
15
- > - Subagents never touch the tracker. Tracker MCP tools (GitHub Issues, Linear, etc.) are orchestrator / workflow-layer exclusive.
15
+ > - Subagents never touch the tracker. Tracker MCP tools (GitHub Issues, Linear, Jira) are orchestrator / workflow-layer exclusive.
16
16
  > - When you change a workflow file (`.bkit/core/workflows/bkit-*.md`), mirror change here.
17
17
 
18
18
  ## File Layout
@@ -81,9 +81,9 @@ Choose by the state of the work. Procedure stays in the command file and in § P
81
81
 
82
82
  ## Tracker Blocks
83
83
 
84
- `.bkit/core/workflows/bkit-*.md` carry wired tracker variants inline (`github`, `linear`) — full per-tracker behaviour (MCP shapes, labels, states) visible at call site. No substitution from `.bkit/trackers.md`; resolver selects/strips inline blocks. Markers:
84
+ `.bkit/core/workflows/bkit-*.md` carry wired tracker variants inline (`github`, `linear`, `jira`) — full per-tracker behaviour (MCP shapes, labels, states) visible at call site. No substitution from `.bkit/trackers.md`; resolver selects/strips inline blocks. Markers:
85
85
 
86
- **Per-tracker pair.** Every tracker call site: consecutive `github` → `linear` pair (no authored `none` — no-tracker rendering = single generic message):
86
+ **Per-tracker group.** Every tracker call site: consecutive `github` → `linear` → `jira` group (no authored `none` — no-tracker rendering = single generic message):
87
87
 
88
88
  ```text
89
89
  <!-- bkit:tracker github start -->
@@ -92,13 +92,16 @@ mcp__github__… call
92
92
  <!-- bkit:tracker linear start -->
93
93
  mcp__linear__… call
94
94
  <!-- bkit:tracker linear end -->
95
+ <!-- bkit:tracker jira start -->
96
+ mcp__jira__… call
97
+ <!-- bkit:tracker jira end -->
95
98
  ```
96
99
 
97
- At `bkit install`: read `bkit.issueTracker` from consumer manifest → keep matching block, drop other when mirroring to `.claude/commands/bkit-*.md` and `.cursor/commands/bkit-*.md`. Under `none` → whole pair collapses to **`_No tracker connected, skip step._`**. List-number prefix (`3. `) preserved on kept block / stub. Sites needing no-tracker function (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`) add trailing `<!-- bkit:tracker false start/end -->` after pair — used under `none` instead of generic message.
100
+ At `bkit install`: read `bkit.issueTracker` from consumer manifest → keep matching block, drop the others when mirroring to `.claude/commands/bkit-*.md` and `.cursor/commands/bkit-*.md`. Under `none` → whole group collapses to **`_No tracker connected, skip step._`**. List-number prefix (`3. `) preserved on kept block / stub. Sites needing no-tracker function (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`) add trailing `<!-- bkit:tracker false start/end -->` after group — used under `none` instead of generic message.
98
101
 
99
- **Conditional blocks (`bkit:tracker true` / `bkit:tracker false`).** Boolean tracker-presence gates for tracker-agnostic content: `true` kept when wired, **removed entirely under `none`** (shared comment `{BODY}` fences, identical github/linear); `false` kept only under `none`. Removed block consumes leading newline — no blank gap.
102
+ **Conditional blocks (`bkit:tracker true` / `bkit:tracker false`).** Boolean tracker-presence gates for tracker-agnostic content: `true` kept when wired, **removed entirely under `none`** (shared comment `{BODY}` fences, identical for every tracker); `false` kept only under `none`. Removed block consumes leading newline — no blank gap.
100
103
 
101
- `github`/`linear` pair only when call **genuinely differs**. Byte-identical bodies → single `true` block — duplicating identical content as pair is redundant. Enforced by `.bkit/core/engine/render/trackers.test.ts` ("no identical github/linear pair"). `none` difference: pair → `_No tracker connected, skip step._` stub; `true` block removed outright — use `true` only where content can vanish under `none` (inline notes, gate items), not where numbered step needs stub to keep number.
104
+ Per-tracker group only when call **genuinely differs**. Byte-identical bodies → single `true` block — duplicating identical content per tracker is redundant. Enforced by `.bkit/core/engine/render/trackers.test.ts` ("no identical github/linear pair"). `none` difference: group → `_No tracker connected, skip step._` stub; `true` block removed outright — use `true` only where content can vanish under `none` (inline notes, gate items), not where numbered step needs stub to keep number.
102
105
 
103
106
  ```text
104
107
  <!-- bkit:tracker true start -->
@@ -110,7 +113,7 @@ At `bkit install`: read `bkit.issueTracker` from consumer manifest → keep matc
110
113
 
111
114
  Limit = `none` rendering. Bare pair collapses to `_No tracker connected, skip step._` — hoisted prose above survives introducing a step that says "skip" (`{QUERY}` with no search, "new comment" with no comment). Hoist only where trailing `false` block supplies real `none` body (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`); at pair-only sites keep shared text inside both blocks so whole step vanishes. Design/debug issue-scan `{QUERY_NL}` prefix + `— NEW comment, no edit.` suffix stay duplicated. **Exception — plan fetch-context (`/bkit-plan` Step 4):** `{QUERY}` hoisted to plain step — tracker-independent local greps (`related-deferrals.md` / `related-failures.md`) in same step consume it and must run under `none`; hoisted definition not orphaned — do not re-duplicate into tracker pair. `{QUERY_NL}` stays inside the pair (search-only, vanishes under `none`).
112
115
 
113
- Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` after `--tracker=github`) → fresh mirrors. Resolver reports lone `github`/`linear` block or unbalanced `true`/`false` pair as orphan — silent regressions unacceptable. New call site → add `github`/`linear` pair inline (no `trackers.md` edit; `none` block only if step must do something without tracker). `.bkit/trackers.md` = reference-only (marker contract + cross-cutting conventions); not substitution source.
116
+ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` after `--tracker=github`) → fresh mirrors. Resolver reports a block outside a full group or unbalanced `true`/`false` pair as orphan — silent regressions unacceptable. New call site → add `github` / `linear` / `jira` group inline (no `trackers.md` edit; `none` block only if step must do something without tracker). `.bkit/trackers.md` = reference-only (marker contract + cross-cutting conventions); not substitution source.
114
117
 
115
118
  **Rationale rehomed from the workflow files** (stripped there per § Workflow Authoring Rules; kept here):
116
119
 
@@ -145,7 +148,7 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
145
148
  - **Adopt mode does no `git worktree add`:** `RUNTIME_WORKTREES` takes the same conservative default as `RUNTIME_DEVPUSHES` (`false` for `CLOUD_CLAUDE` / `UNKNOWN`): a push to `dev` cannot be tested without making it, and a wrong guess strands a session. The claude.ai GitHub proxy does not limit which branches a push can update; it rejects only branch deletions and non-branch pushes such as tags (https://code.claude.com/docs/en/cloud-environments § GitHub proxy). `RUNTIME_WORKTREES=false` works in place on whatever branch the session is already on, with `WORKTREE_PATH=$REPO_ROOT`, and refuses outright if that branch is `dev`. `/bkit-debug` is the exception: it adopts in place in every runtime once there is no `feat/{FID}` to take, `dev` included, because a fix has to land on the branch that went red.
146
149
  - **Ship never checks out `dev`:** Step 13 `bkit branches sync-dev` fetches and fast-forwards local `dev` without a checkout (`git merge --ff-only` + frozen install only when the main checkout is on `dev` and `dev` moved). Local-only `dev` commits → listed with the publish command, never pushed (unreviewed work). Step 14 stays in the feature worktree until the close lands; the close then removes it and `cd`s to `REPO_ROOT`.
147
150
  - **Close-transport audit rows:** `runtime-resolved` (capability table), `transport-fallback` (one gh->MCP transition), `close-transport` (which shape landed which SHA, plus the body-scan result) — all additive, none folded. Written by `bkit runtime row` and `bkit prs transport-row`; read back by `bkit runtime assert` and `bkit prs cross-check`.
148
- - **`FID` slug assertions (`bkit-auto` Step 1, `bkit runs context`):** `bkit fids` holds the regexes (`runs context` checks a CI_DEV slug against the `any` allowlist and recovers a PR's FID with the same marker / branch parsing as `bkit fids parse`); they are allowlists (canonical `^[0-9]+-[a-z0-9-]+$` for GitHub issue-prefixed slugs, `^[a-z]+-[0-9]+-[a-z0-9-]+$` for Linear-prefixed slugs, safe `^[a-z0-9][a-z0-9-]*$` for the no-tracker + branch-derive fallback, tracker-agnostic `^([0-9]+|[a-z]+-[0-9]+)-[a-z0-9-]+$` for the CI_DEV slug arg, `--tracker=any`). They reject path traversal and shell metacharacters in the untrusted PR-body marker before `{FID}` reaches any filesystem path or downstream dispatch. `bkit fids parse` tries the marker first and falls back to the `feat/{FID}` branch only when the marker is missing or malformed, and the fallback must resolve `{ISSUE_ID}` too — from the `{FID}` slug (github: leading numeric segment; linear: first two dash-segments, uppercased), each behind its own allowlist. A fallback that recovers only `{FID}` is dead code on any tracker-wired repo: the Step 1 comment keys every tracker call on `{ISSUE_ID}` and Gate 1 asserts it non-empty, so the run reaches **Failure Path** whatever `{FID}` says. Under the no-tracker variant `{ISSUE_ID}` stays empty by design and the comment is skipped. The branch-derive accepts `feat/**` only — the cloud router's `workflow_run` surface is `feat/**` plus `dev`, and no bkit phase mints any other branch prefix.
151
+ - **`FID` slug assertions (`bkit-auto` Step 1, `bkit runs context`):** `bkit fids` holds the regexes (`runs context` checks a CI_DEV slug against the `any` allowlist and recovers a PR's FID with the same marker / branch parsing as `bkit fids parse`); they are allowlists (canonical `^[0-9]+-[a-z0-9-]+$` for GitHub issue-prefixed slugs, `^[a-z]+-[0-9]+-[a-z0-9-]+$` for Linear-prefixed slugs, `^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$` for Jira-prefixed slugs, safe `^[a-z0-9][a-z0-9-]*$` for the no-tracker + branch-derive fallback, tracker-agnostic `^([0-9]+|[a-z][a-z0-9]*-[0-9]+)-[a-z0-9-]+$` for the CI_DEV slug arg, `--tracker=any`). They reject path traversal and shell metacharacters in the untrusted PR-body marker before `{FID}` reaches any filesystem path or downstream dispatch. `bkit fids parse` tries the marker first and falls back to the `feat/{FID}` branch only when the marker is missing or malformed, and the fallback must resolve `{ISSUE_ID}` too — from the `{FID}` slug (github: leading numeric segment; linear / jira: first two dash-segments, uppercased), each behind its own allowlist. A fallback that recovers only `{FID}` is dead code on any tracker-wired repo: the Step 1 comment keys every tracker call on `{ISSUE_ID}` and Gate 1 asserts it non-empty, so the run reaches **Failure Path** whatever `{FID}` says. Under the no-tracker variant `{ISSUE_ID}` stays empty by design and the comment is skipped. The branch-derive accepts `feat/**` only — the cloud router's `workflow_run` surface is `feat/**` plus `dev`, and no bkit phase mints any other branch prefix.
149
152
  - **Step 1 FID check in every phase workflow:** design, plan, build, debug and ship run `bkit fids check` on the resolved `FID` at Step 1 — whichever sub-step resolved it (session prompt, branch, existing logs, mint) and under every tracker, `none` included (the safe allowlist). A bad `FID` then fails before any work, not at `bkit prs open`, which keeps its own check as a backstop.
150
153
  - **`bkit-auto` CI_DEV mode (`bkit runs context`):** a post-merge `dev` CI failure has no open PR to read, so `bkit-cloud.yml` passes the `{FID}` slug instead of a PR number and `runs context` discriminates on `{ARG}` shape (numeric → PR, else slug). The slug is untrusted at the same level as the PR-body marker — it arrives from a commit-message scope on `dev` and the cloud-side `ARG` guard permits `.` and `/` — so the `any` allowlist is asserted (exit 9) before `{FID}` reaches `docs/plans/{YYYYMM}/logs/{FID}/`, `.worktrees/{FID}`, or the `/bkit-debug {FID} {REF}` dispatch. `prNumber`, `prUrl` and `runId` are printed null rather than filled with a `(merged)` sentinel: the Step 1 comment drops its PR and run links in CI_DEV, and a sentinel would render a broken link. The open check (exit 7) and the CI-run lookup (exit 8) are on the CI path only.
151
154
  - **Auto-route marker derivation is fence-local (build Step 18, debug Step 11, ship Step 10):** every site re-reads the issue's labels through the tracker MCP and hands them as `{LABEL_FLAGS}` to the command that writes the commit — `bkit workflows close --label=` (build / debug close commit), `bkit runs dispatch --label=` (the gate's re-trigger commit), `bkit prs merge --label=` (ship's squash subject) — which appends ` bkit [auto route]` on an exact `bkit:auto` match; no `gh` call. Two dead shapes preceded it and must not return: `${LABELS:-}` (an MCP-derived template value that is never assigned as a shell variable, so it always expanded empty), and a `mktemp` path published via `$GITHUB_ENV` (the runner applies `$GITHUB_ENV` only BETWEEN Action steps, while every agent Bash tool call in a cloud dispatch runs inside the one `claude-code-action` step). The exact label match mirrors the kill switch in `bkit-cloud.yml`, the marker's only consumer, so `bkit:auto-paused` / `no-bkit:auto` cannot arm the route. No tracker (`none`) passes no labels and leaves the subject unchanged. The marker becomes permanent `dev` history; that is inherent to reading `head_commit.message` and is not cleaned up later. Any resulting cross-session `/bkit-debug` dispatch loop is capped by `MAX_DEV_DISPATCH_ATTEMPTS` (a workflow-level env in `bkit-cloud.yml`, held equal to `bkit counters max` by `counters.test.ts`).
@@ -159,27 +162,27 @@ Re-runnable: source carries wired variants; tracker switch (`--tracker=linear` a
159
162
  - **`bkit context finalise` re-reads the configured contexts:** `contextsConfigured` comes from the context file at finalise time, never from a value an earlier block printed — an inherited value records `[]` whenever it is lost between blocks, which is telemetry claiming no contexts were configured on a run that fetched them, and a tracker comment marking all five `NOT CONFIGURED`.
160
163
  - **One `context-fetch` context list and one marker parser:** `CONTEXT_FETCH_CONTEXTS` and `parseContextFetchStart` in `.bkit/core/engine/checks/before/context-fetch.ts`; the `bkit context` runner and the `bkit check` advisories both read them. The consumer table in `.agents/context.md` must list the same contexts — `.bkit/core/engine/audits/templates/context-fetch-contexts.test.ts` asserts it.
161
164
  - **Header `Placeholders:` line is generic on purpose:** workflow headers list only universally-required examples (`{FID}`, `{YYYYMM}`, plus plan's `{PARENT_FID}` / `{PARENT_YYYYMM}`); the rest of the placeholder inventory is asserted at the step that mints / derives each value. Per-placeholder detail: `{OWNER}` and `{REPO}` derived from `{OWNER_REPO}` at Step 1; `{WORKTREE_PATH}` = absolute path set at worktree setup — mint mode (`RUNTIME_WORKTREES=true`): `.worktrees/{FID}`, adopt mode (`RUNTIME_WORKTREES=false`): `$REPO_ROOT` — required for subagent `Context` cwd; `{YYYYMM}` = canonical month bucket for the FID, held from `bkit locks acquire`'s `month`: the feature's existing bucket, else this UTC month — set once at the feature's first start; a feature with logs in two buckets is refused (exit 7). Plan derives `{PARENT_YYYYMM}` from `{PARENT_FID}`'s bucket. Tracker-wired placeholders (`{ISSUE_ID}` / `{STATE}` / `{LABELS}`) asserted inline in each per-tracker `**Tracker:**` row — empty under `none`.
162
- - **Tracker context filtering (`###### bkit:generated` / `###### bkit:ignore-earlier`):** every comment-post template stamps `###### bkit:generated` as its first body line; `###### bkit:ignore-earlier` is human-placed in a body or comment. Both are h6 headings. Detection of both is WHOLE-line and the heading form only. An inline prose mention of a token is never a marker. Both apply at the point of use, never at the fetch — fetch sites return `COMMENTS` raw; the artifact step writes description + comments to files and `bkit issues text --description-file= --comments-file=` joins them into a named variable (`ISSUE_TEXT`; `RELATED_ISSUE_TEXT` per sweep hit), drops marker-carrying comments, then drops everything above the last cut marker. Point-of-use placement lets both steps share one sentence, keeps the fetch sites from drifting apart, and makes the artifact read the named variable and never the raw fields, so the cut cannot be bypassed downstream. Sweep = issue path with a `RELATED_` prefix (`RELATED_DESCRIPTION` / `RELATED_COMMENTS` / `RELATED_ISSUE_TEXT`); keep identical so a change to one is mechanical in the other. Sweep filter + cut must run per hit and accumulator `RELATED_ISSUES` must never be filtered or cut — a marker belongs to its own issue; cutting the concatenation deletes every issue above it. Detection is marker-only: a template-heading-shape fallback needs lockstep maintenance with every template heading and eats human comments sharing a heading; a dedicated h6 whose text is the token is marker-only detection, not a shape fallback. On GitHub, body and comment text via `mcp__github__issue_read` (`get` / `get_comments`); CLI `gh api` is backup only. Ordering: explicit `sort oldest to newest`, same wording per tracker, on every path into `COMMENTS` — including the AGENTS.md skip branch, which bypasses the fetch and arrives newest-first (`AGENTS.md` § Route Step 1). Sort not reverse: correct whatever the call returned (GitHub `/issues/{n}/comments` oldest-first, Linear `list_comments` `orderBy: "createdAt desc"`). Failure is silent — a newest-first stream inverts the cut into keep-superseded / drop-current and still looks trimmed. Not collapsible to a shared `true` block despite identical sort and filter wording: tool names, params and field names differ. **Emitting a cut marker line is prohibited** (`.agents/rules.md` § Tracker context cut): a whole-line `###### bkit:ignore-earlier` in anything the orchestrator posts or writes arms the next run's cut on bkit's own output, deleting the human context above it. Inline mentions of the token are inert. The generated filter is no backstop here: it drops comments only, never an issue body (which the design blocked-by encode rewrites), and never a sweep hit inside `RELATED_ISSUES`. Guards: `commands/workflow/issues.test.ts` (generated drop before cut, last-marker cut, inline mention inert, oldest-first sort); `.bkit/core/engine/audits/workflows/generated-marker.test.ts` fails on any whole-line cut marker in a workflow, this spec, or `.bkit/core/prompts/*.md`.
165
+ - **Tracker context filtering (`###### bkit:generated` / `###### bkit:ignore-earlier`):** every comment-post template stamps `###### bkit:generated` as its first body line; `###### bkit:ignore-earlier` is human-placed in a body or comment. Both are h6 headings. Detection of both is WHOLE-line and the heading form only. An inline prose mention of a token is never a marker. Both apply at the point of use, never at the fetch — fetch sites return `COMMENTS` raw; the artifact step writes description + comments to files and `bkit issues text --description-file= --comments-file=` joins them into a named variable (`ISSUE_TEXT`; `RELATED_ISSUE_TEXT` per sweep hit), drops marker-carrying comments, then drops everything above the last cut marker. Point-of-use placement lets both steps share one sentence, keeps the fetch sites from drifting apart, and makes the artifact read the named variable and never the raw fields, so the cut cannot be bypassed downstream. Sweep = issue path with a `RELATED_` prefix (`RELATED_DESCRIPTION` / `RELATED_COMMENTS` / `RELATED_ISSUE_TEXT`); keep identical so a change to one is mechanical in the other. Sweep filter + cut must run per hit and accumulator `RELATED_ISSUES` must never be filtered or cut — a marker belongs to its own issue; cutting the concatenation deletes every issue above it. Detection is marker-only: a template-heading-shape fallback needs lockstep maintenance with every template heading and eats human comments sharing a heading; a dedicated h6 whose text is the token is marker-only detection, not a shape fallback. On GitHub, body and comment text via `mcp__github__issue_read` (`get` / `get_comments`); CLI `gh api` is backup only. Ordering: explicit `sort oldest to newest`, same wording per tracker, on every path into `COMMENTS` — including the AGENTS.md skip branch, which bypasses the fetch and arrives newest-first (`AGENTS.md` § Route Step 1). Sort not reverse: correct whatever the call returned (GitHub `/issues/{n}/comments` oldest-first, Linear `list_comments` `orderBy: "createdAt desc"`, Jira `listJiraIssueComments` oldest-first). Failure is silent — a newest-first stream inverts the cut into keep-superseded / drop-current and still looks trimmed. Not collapsible to a shared `true` block despite identical sort and filter wording: tool names, params and field names differ. **Emitting a cut marker line is prohibited** (`.agents/rules.md` § Tracker context cut): a whole-line `###### bkit:ignore-earlier` in anything the orchestrator posts or writes arms the next run's cut on bkit's own output, deleting the human context above it. Inline mentions of the token are inert. The generated filter is no backstop here: it drops comments only, never an issue body (which the design blocked-by encode rewrites), and never a sweep hit inside `RELATED_ISSUES`. Guards: `commands/workflow/issues.test.ts` (generated drop before cut, last-marker cut, inline mention inert, oldest-first sort); `.bkit/core/engine/audits/workflows/generated-marker.test.ts` fails on any whole-line cut marker in a workflow, this spec, or `.bkit/core/prompts/*.md`.
163
166
 
164
167
  **Per-tracker operational notes** (rationale kept here, not in the workflow files per § Workflow Authoring Rules):
165
168
 
166
- - **Related-issues scan** (issue-scan): numbered step at design ideate-entry, plan fetch-context, debug fetch-context; `github`/`linear` pair → under `none` collapses to `_No tracker connected, skip step._` (number preserved). Best-effort: semantic search — fetch 15, drop own issue, keep 10 — one comment fetch per hit; `Search unavailable.` on error; never gates, never auto-expands scope (advisory dedup / conflicting-design / prior-incident). All states: closed issues carry strongest dedup signals. Per hit: `## #{number} — {title} ({state})` + `RELATED_ISSUE_TEXT` (issue-path wording, `RELATED_` prefix), appended to `RELATED_ISSUES`; file written once after last hit; design → `related-issues.md` (generate reads `(if present)`, condenses to `## Related Issues` one-liners or `None`); a design hit whose `bkit issues text` exits non-zero (comments did not parse) is skipped and named under its heading (`Skipped: comments did not parse.`), and the design carries on — related issues are background. Plan: `{QUERY}` in plain sub-step → `related-deferrals.md` / `related-failures.md`; `{QUERY_NL}` in the tracker pair → `related-issues.md`; read by `bkit-plan-review-1/2/3`. Debug → `context-related-${DEBUG_ATTEMPT}.md` (`context-*` glob; excluded from `FETCH_VERDICT`). Plan runs fresh scan (standalone plan coverage). No `fields` parameter — the search returns all fields on every hit and must keep doing so; restricting to a subset trades away the content the sweep exists to surface. Artifact is uncapped by decision (§ Context artifact clamping).
169
+ - **Related-issues scan** (issue-scan): numbered step at design ideate-entry, plan fetch-context, debug fetch-context; tracker group → under `none` collapses to `_No tracker connected, skip step._` (number preserved). Best-effort: github / linear semantic search — fetch 15, drop own issue, keep 10; jira keyword JQL (`{QUERY_KW}`, 2-4 terms, one `text ~` per term, ORed, own issue excluded, 10) — one comment fetch per hit; `Search unavailable.` on error; never gates, never auto-expands scope (advisory dedup / conflicting-design / prior-incident). All states: closed issues carry strongest dedup signals. Per hit: `## #{number} — {title} ({state})` + `RELATED_ISSUE_TEXT` (issue-path wording, `RELATED_` prefix), appended to `RELATED_ISSUES`; file written once after last hit; design → `related-issues.md` (generate reads `(if present)`, condenses to `## Related Issues` one-liners or `None`); a design hit whose `bkit issues text` exits non-zero (comments did not parse) is skipped and named under its heading (`Skipped: comments did not parse.`), and the design carries on — related issues are background. Plan: `{QUERY}` in plain sub-step → `related-deferrals.md` / `related-failures.md`; `{QUERY_NL}` (jira `{QUERY_KW}`) in the tracker group → `related-issues.md`; read by `bkit-plan-review-1/2/3`. Debug → `context-related-${DEBUG_ATTEMPT}.md` (`context-*` glob; excluded from `FETCH_VERDICT`). Plan runs fresh scan (standalone plan coverage). No `fields` parameter on github / linear — the search returns all fields on every hit and must keep doing so; restricting to a subset trades away the content the sweep exists to surface. Artifact is uncapped by decision (§ Context artifact clamping).
167
170
  - **Query shape — two variables, not one.** `{QUERY_NL}` = one natural-language sentence, consumed only by the search call; no `sort` / `order` / `orderBy`, no `in:title,body` qualifier (inert in a semantic query), results kept in rank order through the drop-own-issue and keep-first-10 steps or the ranking is discarded before use. The response carries an order but no score, so a relevance THRESHOLD is not implementable — rank position is the only signal. `{QUERY}` = the 3–6 keyword list, plan-only, consumed ONLY by the ledger awk: that awk splits on whitespace and counts distinct term hits with a `>=2 terms` rule, so feeding it a sentence makes every stopword match every line and degrades the scan to "print everything".
168
171
  - **Ledger scans** (plan only, run under `none`): awk counts query-term hits per line (`>=2` distinct terms, or the sole term when one; case-insensitive substring), sorts by hit count desc then line number desc (append-only ledgers → line order is time order), keeps the top 40 per file and footers the total. `cut -f3-` rejoins fields 3..N with tabs, so a literal tab inside a JSONL line survives intact. Backstopped by the `ledger` clamp profile.
169
- - **Projects v2 board sync** (`issue-update-status`): best-effort, never gates; retry once after 5s on failure. `bkit issues labels --board=progress|review --issue= --owner-repo=` builds the three payloads (`addItem`, `listItems`, `updateItem`) from `bkit.githubProject`; `board` null + `boardSkipped` when opted out or not configured. `update_project_item` needs numeric `item_id`, not node id from `add_project_item` → intervening `projects_list` resolve. Status `value` = single-select option id (e.g. `47fc9ee4`), not name. Linear: no-op (state carries status).
170
- - **Blocked-by edges:** GitHub: `###### bkit:blocked-by start` / `end` pair in issue body. Linear: native `blockedBy` (append-only; unchanged edges = no-op).
171
- - **No tracker-issue creation:** Workflows never create tracker issues. `issue_write` method is `update`. Linear `save_issue` always includes `id`. Step 1 resolves an existing issue reference from the session prompt; no match → log `No issue ID in the session prompt.` and stop (not **Failure Path**). Design Step 11 posts `## Suggested Workstreams` as an advisory comment on the parent issue. A human files any follow-up issues.
172
- - **issue-update-review** (phase-close): **update state only — never change label on close.** GitHub: no-op (phase label until ship `issue-update-merged`). Linear: `save_issue({ id, state: "In Review" })` — no `labels` (partial update would drop `bkit:auto`/`bkit:debug`).
173
- - **issue-update-merged** (ship terminal): bkit **never auto-closes / never sets Done**. Ship drops phase labels, adds `bkit:merged`, **In Review** — Linear `state: "In Review"`, GitHub **open** (board → review, not done). Human reviews merged change and closes manually. Merge != acceptance.
172
+ - **Projects v2 board sync** (`issue-update-status`): best-effort, never gates; retry once after 5s on failure. `bkit issues labels --board=progress|review --issue= --owner-repo=` builds the two payloads (`addItem`, `updateItem`) from `bkit.github.project`; `board` null + `boardSkipped` when opted out, not configured or not a board URL. `updateItem` names the item by `item_owner` / `item_repo` / `issue_number` and sets `Status` to the option named `bkit.github.progress` / `review` (`In progress` / `In review`). Linear / Jira: no-op (state / status carries it).
173
+ - **Blocked-by edges:** GitHub: `###### bkit:blocked-by start` / `end` pair in issue body. Linear: native `blockedBy` (append-only; unchanged edges = no-op). Jira: native `Blocks` link (`inwardIssue` = blocker; repeat = no-op).
174
+ - **No tracker-issue creation:** Workflows never create tracker issues. `issue_write` method is `update`. Linear `save_issue` always includes `id`. Jira: no `createJiraIssue` grant. Step 1 resolves an existing issue reference from the session prompt; no match → log `No issue ID in the session prompt.` and stop (not **Failure Path**). Design Step 11 posts `## Suggested Workstreams` as an advisory comment on the parent issue. A human files any follow-up issues.
175
+ - **issue-update-review** (phase-close): **update state only — never change label on close.** GitHub: no-op (phase label until ship `issue-update-merged`). Linear: `save_issue({ id, state: "{TRACKER_STATE}" })` (`bkit.linear.review`) — no `labels` (partial update would drop `bkit:auto`/`bkit:debug`); a team without that state → `Unapplied`, issue stays started (`.bkit/trackers.md` § linear — notes). Jira: transition to `bkit.jira.review`, no label edit; unreachable → `Unapplied` (`.bkit/trackers.md` § jira — setup and notes).
176
+ - **issue-update-merged** (ship terminal): bkit **never auto-closes / never sets Done**. Ship drops phase labels, adds `bkit:merged`, **In Review** — GitHub **open** (board → review, not done), Linear `bkit.linear.review`, Jira `bkit.jira.review` (never category `done`). Human reviews merged change and closes manually. Merge != acceptance.
174
177
 
175
178
  ## Two-Layer Separation Rules
176
179
 
177
- > **Agents never call tracker MCP tools.** Tracker MCP tools (`mcp__github__issue_*`, `mcp__linear__*_issue`, `*_comment`, `list_issues`, etc.) are exclusive to the workflow layer. Agent that calls a tracker is a protocol violation. Sole exception: `bkit-utility-update-roadmap` holds read-only grants (`list_issues`, `issue_read` / `get_issue`) and never writes.
180
+ > **Agents never call tracker MCP tools.** Tracker MCP tools (`mcp__github__issue_*`, `mcp__linear__*_issue`, `mcp__jira__*`, `*_comment`, `list_issues`, etc.) are exclusive to the workflow layer. Agent that calls a tracker is a protocol violation. Exceptions, both human-invoked utilities: `bkit-utility-update-roadmap` holds read-only grants (`list_issues`, `issue_read` / `get_issue`, `searchJiraIssuesUsingJql` / `getJiraIssue`) and never writes; `bkit-utility-update-tracker` reads and writes issue fields (title, labels, board status, priority, size, milestone, parent, blocked-by) and never creates, closes or comments, never touches `bkit:*` labels.
178
181
 
179
182
  <!-- prettier-ignore -->
180
183
  | Capability | Workflow (`.bkit/core/workflows/`) | Agent (`.bkit/core/prompts/`) |
181
184
  | --- | --- | --- |
182
- | Invoke tracker MCP | ✅ | ❌ (read-only exception: `bkit-utility-update-roadmap`) |
185
+ | Invoke tracker MCP | ✅ | ❌ (exceptions: `bkit-utility-update-roadmap` read-only, `bkit-utility-update-tracker` field writes) |
183
186
  | Read/write `docs/` | ✅ | ✅ |
184
187
  | Read/write source | via subagent delegation | ✅ (gated by tool surface) |
185
188
  | Run `git` | ✅ (`add`, `commit`, `push`, worktree ops) | read-only checks (`status`, `branch`, `log`) only |
@@ -198,7 +201,7 @@ Every phase command (`design`, `plan`, `build`, `debug`, `ship`) shares skeleton
198
201
  3. Execution Protocol caution block (header bullets — see below)
199
202
  4. Failure Path
200
203
  5. Step 1 — Start Workflow (`bkit repo info --fetch`, FID, `bkit locks acquire`, tracker init, first-step comment post — status init deferred to Step 2; ZERO commits on `dev`)
201
- 6. Step 2 — Worktree Setup (`bkit worktrees setup`: create / resume / adopt; create / resume under `bkit.disk.minFreeGb` free → `max` disk-prune steps first, still under → exit 12 (`.bkit/templates.md` § Disk prune); copy `bkit.worktree.copy` (default `.env`, `.env.local`), install unless `bkit.worktree.install` is false; `bkit workflows start` + `bkit runtime row`; save input; `start-workflow` + `worktree-setup` step entries committed on `feat/{FID}`)
204
+ 6. Step 2 — Worktree Setup (`bkit worktrees setup`: create / resume / adopt; create / resume under `bkit.disk.minFreeGb` free → `max` disk-prune steps first, still under → exit 12 (`.bkit/templates.md` § Disk prune); copy `bkit.worktree.copy` (default `.env`, `.env.local`), `direnv allow` a `.envrc` identical to the main checkout's, install unless `bkit.worktree.install` is false; `bkit workflows start` + `bkit runtime row`; save input; `start-workflow` + `worktree-setup` step entries committed on `feat/{FID}`)
202
205
  7. Phase-specific steps (subagent invocations, gates, per-step new comment post)
203
206
  8. Summary step (subagent → commit → push → verdict)
204
207
  9. Close Workflow (`bkit workflows close`, lock release, state → hand-off via `issue-update-review`; ship terminal `bkit:merged` + In Review via `issue-update-merged` (issue left OPEN — human reviews + closes); non-ship phases update state only, phase label unchanged; **final return** = verbatim `{phase}-summary.md` to user, then a plain-English offer, as the last actions)
@@ -421,7 +424,7 @@ Cross-block routing values re-read from `status.jsonl` with `bkit status route -
421
424
 
422
425
  ### Comment Lifecycle
423
426
 
424
- Every workflow step posts new tracker comment via inline `comment-post-step` block (per-tracker `github`/`linear`/`none`, resolved at install; § Tracker Blocks). never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior content. Each step independent — no comment-ID carry-forward, no body concatenation. `bkit issues comment` builds every body below (`--kind=step|failure|handover|audit`, header fields in flag order, `###### bkit:generated` first, a copied whole-line cut marker defused, stderr fenced) and prints it; the tracker MCP call posts it — the command never touches the tracker.
427
+ Every workflow step posts new tracker comment via inline `comment-post-step` block (per-tracker `github` / `linear` / `jira` / `none`, resolved at install; § Tracker Blocks). never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior content. Each step independent — no comment-ID carry-forward, no body concatenation. `bkit issues comment` builds every body below (`--kind=step|failure|handover|audit`, header fields in flag order, `###### bkit:generated` first, a copied whole-line cut marker defused, stderr fenced) and prints it; the tracker MCP call posts it — the command never touches the tracker.
425
428
 
426
429
  **Step 1 (first comment):**
427
430
 
@@ -711,7 +714,7 @@ Then assert each Update/Create artifact exists, non-empty. Empty → **Failure P
711
714
  | `MAX_MERGE_ATTEMPT` | 3 | `/bkit-ship` PR merge retries |
712
715
  | `MAX_REVALIDATE_ATTEMPT` | 3 | `/bkit-ship` poll-only Step 9 re-entries after a gate refusal (10/11/14/17) |
713
716
  | `MAX_DEV_DISPATCH_ATTEMPTS` | 3 | `bkit-cloud.yml` — distinct failed `dev` CI SHAs per FID that may each dispatch `/bkit-debug` |
714
- | Grill rounds | 10 | `/bkit-design` Step 3 interview cap; literal in the step, not in `THRESHOLDS` |
717
+ | Grill rounds | 10 | `/bkit-design` Step 3 interview cap, draft scenario round included (decision rounds <= 9); literal in the step, not in `THRESHOLDS` |
715
718
  | Step timeout | 3600s | Any workflow or subagent run exceeding this → Failure Path; `/bkit-design` Step 3 time waiting on human answers does not count |
716
719
  | Lock idle threshold | 1800s | Concurrent-run cut-off: holder `IN_PROGRESS` with last-step age <30min → Failure Path; any other holder reclaimed at once (`WORKFLOW_LOCK_IDLE_S`, `commands/workflow/locks.ts`) |
717
720
  | Close retries | 10 / 2s→30s | every dev landing (design / plan / ship close, ship Failure Path record, build / debug roadmap mirror): pushes when `dev` moved underneath; design / plan PR merge tries (`LAND_ATTEMPTS` each); wait before each retry doubles from `LAND_BACKOFF_START_S` up to `LAND_BACKOFF_CAP_S`, jittered down by up to half — at most 3min of waiting in all |
@@ -727,7 +730,7 @@ Every command has `## 🤖 Failure Path` before Step 1. Any step / tool / gate f
727
730
 
728
731
  **Standard failure (always):**
729
732
 
730
- 1. Write the error text to `{OUTBOX_ROOT}/error.md`, then one call: `bkit workflows fail --workflow= --fid= --month= --token={LOCK_TOKEN} [--max-exceeded] {LABEL_FLAGS} --step-number= --step-title= --sub-step= --error-file="{OUTBOX_ROOT}/error.md" [--stderr-file=]` (ship adds `--pr=`). State is changed only with a `--token` (an empty one counts as absent: the failure came before Step 1 took the lock): appends `workflow-failed` (nothing when `status.jsonl` does not exist yet), aborts a rebase in progress in the run's worktree, releases the caller's own lock (another owner's stays, reported as `lock.heldBy`), clears the sentinels (`.rebase-failed`; ship `.deferred-blocked`). Exit 5 = the lock file survived; the printed comment already says `Lock removal failed`. It always prints `labels` (the current labels plus `bkit:failed`; a ship whose `--pr` already MERGED also moves to `bkit:merged`), `linearState`, `handoverNeeded` (`--max-exceeded`, a sentinel existed, or a debug run in `SOAK`), and the `### Workflow Failure` `comment`. No dev push.
733
+ 1. Write the error text to `{OUTBOX_ROOT}/error.md`, then one call: `bkit workflows fail --workflow= --fid= --month= --token={LOCK_TOKEN} [--max-exceeded] {LABEL_FLAGS} --step-number= --step-title= --sub-step= --error-file="{OUTBOX_ROOT}/error.md" [--stderr-file=]` (ship adds `--pr=`). State is changed only with a `--token` (an empty one counts as absent: the failure came before Step 1 took the lock): appends `workflow-failed` (nothing when `status.jsonl` does not exist yet), aborts a rebase in progress in the run's worktree, releases the caller's own lock (another owner's stays, reported as `lock.heldBy`), clears the sentinels (`.rebase-failed`; ship `.deferred-blocked`). Exit 5 = the lock file survived; the printed comment already says `Lock removal failed`. It always prints `labels` (the current labels plus `bkit:failed`; a ship whose `--pr` already MERGED also moves to `bkit:merged`), `trackerState`, `handoverNeeded` (`--max-exceeded`, a sentinel existed, or a debug run in `SOAK`), and the `### Workflow Failure` `comment`. No dev push.
731
734
  2. Write the labels through the tracker MCP; post `comment`.
732
735
 
733
736
  **Conditional handover** — only when `handoverNeeded` **and** a worktree exists (handover agent `cd`s `{WORKTREE_PATH}`; `/bkit-debug` decides `DEBUG_MODE` at Step 1 before the worktree — a pre-worktree failure goes straight to STOP):
@@ -749,7 +752,7 @@ Every command has `## 🤖 Failure Path` before Step 1. Any step / tool / gate f
749
752
 
750
753
  ### Rebase Conflict Tiering
751
754
 
752
- `/bkit-build`, `/bkit-debug`, `/bkit-design`, `/bkit-plan` Step 2 rebase a resumed feature worktree onto `origin/dev` (`bkit worktrees setup`); `/bkit-ship` never rebases its branch — Step 4 integrates (B1 server-side, B2 conflict-resolve). Three-tier recovery:
755
+ `/bkit-build`, `/bkit-debug`, `/bkit-design`, `/bkit-plan` Step 2 rebase a resumed feature worktree onto its base, `origin/dev` or local `dev` when it is ahead (`bkit worktrees setup`); `/bkit-ship` never rebases its branch — Step 4 integrates (B1 server-side, B2 conflict-resolve). Three-tier recovery:
753
756
 
754
757
  <!-- prettier-ignore -->
755
758
  | Tier | Conflict shape | Recovery | Mechanism |
@@ -838,8 +841,8 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
838
841
  | Step | Subagent(s) | Read | Write | Notes |
839
842
  | --- | --- | --- | --- | --- |
840
843
  | 1 — Start Workflow | — | tracker issue | `.lock`, tracker comment | Fetch `origin/dev`. Resolve `{ISSUE_ID}` from the session prompt (no match → stop; never create), set label `bkit:design`, state `In Progress`. no commits on `dev` — `status.jsonl` init + `start-workflow` step entry deferred to Step 2 inside the worktree. |
841
- | 2 — Worktree Setup | — | repo | `.worktrees/{FID}`, `bkit.worktree.copy` files, `design-input-{RUN}.md` | `bkit worktrees setup`: create `feat/{FID}` off a freshly fetched `origin/dev`, resume it, or adopt the current branch in place; dependencies installed (install failure → **Failure Path**). `baseSha` → `runtime-resolved` row (§ Anchor Block). |
842
- | 3 — Grill | — | `design-input-{RUN}.md`, newest earlier-run `design-grill-*.md` | `design-grill-{RUN}.md`, `Grill decisions` section appended to `design-input-{RUN}.md`, tracker comment (`--comment-body`) | Orchestrator interviews the human before any design work. Method adapted from Matt Pocock's `grilling` skill (MIT, https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling). Open decisions mapped as a tree; each round asks the whole frontier (every decision whose prerequisites are settled), numbered, each with a recommended answer worded so "yes" accepts it; plain text, no host question tool. Orchestrator looks up facts; only decisions go to the human. Stops on an empty frontier plus human confirmation, a human stop, or 10 rounds. Agreed answers → `Settled`; unanswered at stop → `Assumed, not confirmed`; "don't know" → `Open`. An earlier run's `Settled` entries stay settled. `grill=false` in the session prompt skips the interview; the artifact then reads `Skipped (grill=false).` `runtimeHeadless` = true (read via `bkit runtime assert`) → no question asked, no turn ended: the tree is walked taking each recommended answer as given, every new answer lands in `Assumed, not confirmed`, and the artifact carries a `Headless run ({RUNTIME})` line. The ideate triplet, generate and both reviewers read the section through `design-input-{RUN}.md`. Waiting time is exempt from the 3600s timeout. A `bkit-cloud.yml` `workflow_dispatch` run is headless. |
844
+ | 2 — Worktree Setup | — | repo | `.worktrees/{FID}`, `bkit.worktree.copy` files, `design-input-{RUN}.md` | `bkit worktrees setup`: create `feat/{FID}` off a freshly fetched `origin/dev` (local `dev` when it is ahead), resume it, or adopt the current branch in place; dependencies installed (install failure → **Failure Path**). `baseSha` → `runtime-resolved` row (§ Anchor Block). |
845
+ | 3 — Grill | — | `design-input-{RUN}.md`, newest earlier-run `design-grill-*.md` | `design-grill-{RUN}.md`, `Grill decisions` section appended to `design-input-{RUN}.md`, tracker comment (`--comment-body`) | Orchestrator interviews the human before any design work. Method adapted from Matt Pocock's `grilling` skill (MIT, https://github.com/mattpocock/skills/tree/main/skills/productivity/grilling). Open decisions mapped as a tree; each round asks the whole frontier (every decision whose prerequisites are settled), numbered, each with a recommended answer worded so "yes" accepts it; plain text, no host question tool. Orchestrator looks up facts; only decisions go to the human. Decision rounds stop on an empty frontier, a human stop, or 9 rounds. The last round asked is always the draft scenario round, counted in the 10-round cap: the orchestrator drafts the acceptance scenario (`Narrative`, `Success Criteria`, `Key Edge Cases`, `Process Sketch` — the four parts of the design's `Acceptance Scenario`) from the whole context — session prompt, issue description and comments, answers, looked-up facts — shows it in full, and asks one question per part it inferred plus a final accept question; an answer that opens new decisions returns to the decision rounds while rounds remain. Agreed answers → `Settled`; unanswered at stop → `Assumed, not confirmed`; "don't know" → `Open`. The draft lands under `### Draft Acceptance Scenario` behind a `DRAFT only` first line saying whether a human reviewed it; a human stop skips the draft round and records the draft unreviewed. `bkit-design-generate` starts its `Acceptance Scenario` from the draft and records each change as a `Decisions` row, with no further confirmation item: the human reviews the scenario again at the plan's `Acceptance Scenario confirmed` box. The plan reads the design, never the draft. An earlier run's `Settled` entries stay settled and its draft is the starting draft. `grill=false` in the session prompt skips the interview; the artifact then reads `Skipped (grill=false).` `runtimeHeadless` = true (read via `bkit runtime assert`) → no question asked, no turn ended: the tree is walked taking each recommended answer as given, every new answer lands in `Assumed, not confirmed`, the draft scenario is written unreviewed, and the artifact carries a `Headless run ({RUNTIME})` line. The ideate triplet, generate and both reviewers read the section through `design-input-{RUN}.md`. Waiting time is exempt from the 3600s timeout. A `bkit-cloud.yml` `workflow_dispatch` run is headless. |
843
846
  | 4 — Brainstorm & Ideate | `@bkit-design-brainstorm-ideate-1` ‖ `-2` ‖ `-3` (parallel triplet) | `design-input-{RUN}.md` | `design-brainstorm-ideate-1.md`, `-2.md`, `-3.md` | Pragmatic / optimal-tradeoff / risk-premortem lenses; effort-tier diversity (`high`/`medium`/`high`); sibling-blind. `BRAINSTORM_VERDICT` = worst of three. |
844
847
  | 5 — Generate Design | `@bkit-design-generate` | `design-input-{RUN}.md` (carries the `Grill decisions` section), all three brainstorms, `related-issues.md`, superseded `{YYYYMM}/{FID}-design.md` (if any) | `design-v1-draft.md` (versioned draft) | First write of deliverable design doc. Superseded design = context only, never a constraint; supplied HERE only — not to the sibling-blind ideate triplet. |
845
848
  | 6 — Design Review | `@bkit-design-review-1` ‖ `@bkit-design-review-2` (parallel) | `design-v1-draft.md`, `design-input-{RUN}.md` | `design-review-1.md`, `design-review-2.md` (opinion-only logs) | Effort-tier diversity (high vs medium); sibling-blind. `REVIEW_VERDICT` = worst of two. FAIL → Failure Path. `SPIKE` = `Spike` header from `design-review-1.md` only. |
@@ -997,7 +1000,7 @@ Each subsection documents command behaviour — steps, subagents, artifacts, ver
997
1000
 
998
1001
  ### Audits
999
1002
 
1000
- No command and no phase label. A template in `docs/templates/bkit-audit-*.md` is the procedure (sections, steps, gates). `@bkit-audit-generate` runs one template and writes `docs/audits/{YYYYMM}/{slug}.md`. **If** that month already has this slug → `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Writes only the report and the template's consumer-owned `Project Instructions` below `bkit:end`, refined each run. Issue named in the input + tracker wired → posts the final summary there as one `--kind=audit` comment (`### Audit Summary: {slug}`), `STOPPED` runs included; never gates. Final return appends what `bkit tips --workflow=audit` prints (one tip, then how to silence it; no star line) as `## bkit Tips`, then offers a plain-English explanation on request. `/bkit-plan` reads a design doc, one or more of those reports, or both.
1003
+ No command and no phase label. A template in `docs/templates/bkit-audit-*.md` is the procedure (sections, steps, gates). `@bkit-audit-generate` runs one template and writes `docs/audits/{YYYYMM}/{slug}.md`. **If** that month already has this slug → `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Writes only the report and the template's consumer-owned `Project Instructions` below `bkit:end`, refined each run. Issue named in the input + tracker wired → posts the final summary there as one `--kind=audit` comment (`### Audit Summary: {slug}`), `STOPPED` runs included; never gates. No issue named + tracker wired → read-only search for the template's audit parent (`.bkit/trackers.md` § Issue shapes); found → summary posted there; none open → `Recommended Next Step` suggests one, with the built comment saved to `{OUTBOX_ROOT}/audit-{slug}/parent-comment.md` to post as its first comment. `Suggested Issues` rows are always filed as sub-issues of the parent, existing or new. Final return appends what `bkit tips --workflow=audit` prints (one tip, then how to silence it; no star line) as `## bkit Tips`, then offers a plain-English explanation on request. `/bkit-plan` reads a design doc, one or more of those reports, or both.
1001
1004
 
1002
1005
  ### `/bkit-auto` — phase-routed dispatch
1003
1006
 
@@ -1007,7 +1010,7 @@ No command and no phase label. A template in `docs/templates/bkit-audit-*.md` is
1007
1010
  | Step | Notes |
1008
1011
  | --- | --- |
1009
1012
  | 1 — Start Workflow | `bkit repo info --allow-detached` (holds `{BKIT}`, `{OUTBOX_ROOT}`), then one `bkit runs context --phase={PHASE} --arg={ARG}`: classifies `{PHASE}` → `MODE` (CI-status aliases `success`/`pass` → `ship`, `failure`/`fail` → `debug` let the Cursor dashboard paste `/bkit-auto $CI_STATUS $PR_NUMBER` literally; unknown → exit 3). `MODE` = CI: `gh pr view {ARG}` → branch / head / state (open required, exit 7) / URL; the CI run at that head (exit 8 when none); `{FID}` + `{ISSUE_ID}` from the PR-body marker, else the `feat/{FID}` branch (exit 9 when neither parses); `gh` missing → exit 80 → **Failure Path**. `MODE` = CI_DEV: `{ARG}` is the `{FID}` slug itself (allowlist first), `{ISSUE_ID}` = its leading issue segment, `BRANCH` = `dev`, `HEAD_SHA` = `origin/dev`; no PR, no run link. `MODE` = brief: `{ISSUE_ID}` = `{ARG}`. Gate 1 = `bkit steps gate --placeholder=` for the mode's values. The dispatched skill owns FID / `status.jsonl` / worktree. Create fresh tracker comment header. **Stateless — no `status.jsonl`, no `dev` commit.** |
1010
- | 2 — Dispatch | Derive `{REF}` — the issue reference in a shape the dispatched workflow's own Step 1 parses (`#N` for GitHub, `ABC-123` for Linear). Route `{PHASE}` → `/bkit-ship {FID} {REF}` / `/bkit-debug {FID} {REF}` / `/bkit-design {REF}` / `/bkit-plan {REF}` / `/bkit-build {REF}`. Invoke via `Skill` (Claude) / `Task` (Cursor); dispatched skill owns its session from there. The regression-gate-verification gate that catches Vercel-ignore / partial-tier demotion lives in `/bkit-ship` Step 2 — Regression Guard (universal — also applies to manual `/bkit-ship` invocations that bypass the workflow). |
1013
+ | 2 — Dispatch | Derive `{REF}` — the issue reference in a shape the dispatched workflow's own Step 1 parses (`#N` for GitHub, `ABC-123` for Linear / Jira). Route `{PHASE}` → `/bkit-ship {FID} {REF}` / `/bkit-debug {FID} {REF}` / `/bkit-design {REF}` / `/bkit-plan {REF}` / `/bkit-build {REF}`. Invoke via `Skill` (Claude) / `Task` (Cursor); dispatched skill owns its session from there. The regression-gate-verification gate that catches Vercel-ignore / partial-tier demotion lives in `/bkit-ship` Step 2 — Regression Guard (universal — also applies to manual `/bkit-ship` invocations that bypass the workflow). |
1011
1014
 
1012
1015
  **CI-class skip conditions:** one tracker no-op line, exit 0. Only real failures (missing args, tracker unreachable, malformed state) → Failure Path. Loop bound: `/bkit-debug` enforces `MAX_DEBUG_ATTEMPT` = 3 internally; cloud never counts attempts.
1013
1016
 
@@ -1020,15 +1023,16 @@ All phase workflows run in `.worktrees/{FID}` (gitignored). One worktree per FID
1020
1023
  <!-- prettier-ignore -->
1021
1024
  | Mode | When | Does |
1022
1025
  | --- | --- | --- |
1023
- | `created` | `--worktrees`, no `.worktrees/{FID}` | `git worktree prune`; adds the existing local `feat/{FID}`, else tracks `origin/feat/{FID}`, else cuts `feat/{FID}` off a freshly fetched `origin/dev` (explicit refspec — a clone whose fetch refspec skips `dev` still gets a current base; origin unreachable → exit 4, nothing minted). Writes the `.worktree-owned` marker in `{OUTBOX}` |
1024
- | `resumed` | `--worktrees`, `.worktrees/{FID}` registered | `git fetch origin dev` + `git rebase origin/dev` (ship: no fetch, no rebase). Conflict → exit 3, rebase left in progress (§ Rebase Conflict Tiering); a rebase that cannot start → exit 9. A plain directory at the path → exit 10, never rebases the main checkout |
1026
+ | `created` | `--worktrees`, no `.worktrees/{FID}` | `git worktree prune`; adds the existing local `feat/{FID}`, else tracks `origin/feat/{FID}`, else cuts `feat/{FID}` off the base: a freshly fetched `origin/dev` (explicit refspec — a clone whose fetch refspec skips `dev` still gets a current base; origin unreachable → exit 4, nothing minted), or local `dev` when it is a fast-forward of `origin/dev` — dev pushes wait for a human, so local `dev` routinely holds commits `origin/dev` lacks; push `dev` before the feature PR. Local `dev` diverged from `origin/dev` → `origin/dev`, narrated. Writes the `.worktree-owned` marker in `{OUTBOX}` |
1027
+ | `resumed` | `--worktrees`, `.worktrees/{FID}` registered | `git fetch origin dev` + `git rebase` onto the same base (ship: no fetch, no rebase). Conflict → exit 3, rebase left in progress (§ Rebase Conflict Tiering); a rebase that cannot start → exit 9. A plain directory at the path → exit 10, never rebases the main checkout |
1025
1028
  | `adopted` | no `--worktrees` (cloud), or the session already sits on the branch | works in place on the current branch, `worktreePath` = repo root; no copy, no install |
1026
1029
 
1027
1030
  Then, for `created` / `resumed` worktrees only:
1028
1031
 
1029
1032
  - **Copy:** each `package.json` `bkit.worktree.copy` entry (default `.env`, `.env.local`; files or folders) from the main checkout; `copied` / `copyMissing` list them and every missing entry is narrated — never a hard-coded app path. An entry pointing outside the main checkout is skipped.
1030
1033
  - **Install:** every workflow (`bkit.worktree.install`, default true), frozen lockfile through the package manager — required because per-package `node_modules` symlinks are not inherited by worktrees, and without the install there is no `.husky/_`, so commits and pushes in the worktree skip the hooks. Install failure → exit 5; a package manager that could not run → exit 6; both → **Failure Path** in every workflow.
1031
- - `logDir` created; `baseSha` = `git merge-base origin/dev HEAD` (design / plan anchor).
1034
+ - **direnv:** a worktree `.envrc` byte-identical to the main checkout's gets `direnv allow` (`direnvAllowed`), so the worktree carries the trust given there and nothing more. A differing `.envrc`, direnv missing or failing → narrated, never fatal; a human reads it and runs `direnv allow`. No git hook can do it: `core.hooksPath` (`.husky/_`) exists only after the install.
1035
+ - `logDir` created; `baseRef` = the base above; `baseSha` = `git merge-base {baseRef} HEAD` (design / plan anchor).
1032
1036
 
1033
1037
  Refused (exit 7): `dev` / `main` as the working branch (debug: `main` only), a detached HEAD, or ship unable to switch to its branch.
1034
1038
 
@@ -1039,7 +1043,7 @@ Refused (exit 7): `dev` / `main` as the working branch (debug: `main` only), a d
1039
1043
  <!-- prettier-ignore -->
1040
1044
  | Workflow | Branch | Reason |
1041
1045
  | --- | --- | --- |
1042
- | `/bkit-design`, `/bkit-plan`, `/bkit-build` | `feat/{FID}` — local, else `origin`, else cut off `origin/dev` | One branch per feature; every phase starts from current `dev`. |
1046
+ | `/bkit-design`, `/bkit-plan`, `/bkit-build` | `feat/{FID}` — local, else `origin`, else cut off `origin/dev` (local `dev` when it is ahead) | One branch per feature; every phase starts from current `dev`. |
1043
1047
  | `/bkit-ship` | `--branch=` (the prompt names it), else `feat/{FID}` when it exists locally or on `origin`, else the session branch when it is not `dev` / `main`, else `feat/{FID}` off `origin/dev` | The prompt is the authority on what to ship (§ Branch eligibility). |
1044
1048
  | `/bkit-debug` | existing `feat/{FID}`, else the session's current branch in place (`dev` included; `main` refused) | A remediation branch of its own would strand the fix off the surface whose CI actually failed, and mint a new one on every run. |
1045
1049
 
@@ -1061,7 +1065,7 @@ Refused (exit 7): `dev` / `main` as the working branch (debug: `main` only), a d
1061
1065
 
1062
1066
  ## Tracker Integration
1063
1067
 
1064
- Pluggable via `bkit install --tracker=<github|linear|none>`. Per-tracker MCP endpoints, tool names, call shapes inline at each site as `github`/`linear`/`none` blocks; installer keeps chosen, drops others when mirroring `.claude/commands/` + `.cursor/commands/` (§ Tracker Blocks). `.bkit/trackers.md` = marker contract + cross-cutting conventions only.
1068
+ Pluggable via `bkit install --tracker=<github|linear|jira|none>`. Per-tracker MCP endpoints, tool names, call shapes inline at each site as `github` / `linear` / `jira` / `none` blocks; installer keeps chosen, drops others when mirroring `.claude/commands/` + `.cursor/commands/` (§ Tracker Blocks). `.bkit/trackers.md` = marker contract + cross-cutting conventions only.
1065
1069
 
1066
1070
  ### Phase labels (mutually exclusive)
1067
1071
 
@@ -1077,7 +1081,7 @@ Phase labels carry `bkit:` namespace — no consumer clash. Mutual exclusion in
1077
1081
  | `bkit:ship` | `/bkit-ship` running |
1078
1082
  | `bkit:merged` | `/bkit-ship` completed; PR merged to `dev`; issue left **In Review** (open) — a human reviews post-merge and closes manually (bkit never auto-closes) |
1079
1083
 
1080
- Phase label preserved through Close — tracker state (Linear "In Review", GitHub `open`) carries completion signal; label tells reviewers which workflow finished and names the next best one (`bkit:design` → plan, `bkit:plan` → build, `bkit:build` / `bkit:debug` → ship; with `bkit:failed` → debug). Ship exception: Close swaps `bkit:ship` → `bkit:merged`.
1084
+ Phase label preserved through Close — tracker state (GitHub `open`, Linear / Jira review state) carries completion signal; label tells reviewers which workflow finished and names the next best one (`bkit:design` → plan, `bkit:plan` → build, `bkit:build` / `bkit:debug` → ship; with `bkit:failed` → debug). Ship exception: Close swaps `bkit:ship` → `bkit:merged`.
1081
1085
 
1082
1086
  ### Additive labels (do not drop phase)
1083
1087
 
@@ -1089,16 +1093,16 @@ Phase label preserved through Close — tracker state (Linear "In Review", GitHu
1089
1093
 
1090
1094
  ### Tracker-specific state
1091
1095
 
1092
- Issue state semantics (Linear "In Progress" / "In Review" / "Done"; GitHub `open`/`closed` + Projects v2) inline as per-tracker blocks:
1096
+ Issue state semantics (GitHub `open`/`closed` + Projects v2; Linear / Jira `progress` / `review` from `bkit.linear` / `bkit.jira`, never done) inline as per-tracker blocks:
1093
1097
 
1094
1098
  <!-- prettier-ignore -->
1095
1099
  | Snippet | When |
1096
1100
  | --- | --- |
1097
1101
  | `issue-update-phase` | Step 1 of every phase. Sets phase label, tracker-specific "active" state. |
1098
- | `issue-update-review` | Close Workflow of `/bkit-design`, `/bkit-plan`, `/bkit-build`, `/bkit-debug`. Hand-off state (Linear "In Review"; GitHub no-op — phase label carries signal). |
1099
- | `issue-update-merged` | `/bkit-ship` Step 14. Ship terminal — drop phase labels, add `bkit:merged`; Linear "In Review", GitHub left **open**. bkit never closes / never sets Done — a human closes on acceptance (merge != acceptance). |
1102
+ | `issue-update-review` | Close Workflow of `/bkit-design`, `/bkit-plan`, `/bkit-build`, `/bkit-debug`. Hand-off state (GitHub no-op — phase label carries signal; Linear / Jira `review`). |
1103
+ | `issue-update-merged` | `/bkit-ship` Step 14. Ship terminal — drop phase labels, add `bkit:merged`; GitHub left **open**, Linear / Jira `review`. bkit never closes / never sets Done — a human closes on acceptance (merge != acceptance). |
1100
1104
  | `issue-update-failed` | Failure Path. Adds `bkit:failed` additive label. |
1101
- | `issue-update-status` | Step 1 (design/plan/build/debug/ship) → "In progress"; phase Close (design/plan/build/debug) → "In review"; `/bkit-ship` Step 14 → "In review" (never "Done" — the board mirrors the issue, which stays open for human close). GitHub Projects v2 board (`bkit.githubProject`; skipped if unset/absent). Linear no-op (issue state already carries it). |
1105
+ | `issue-update-status` | Step 1 (design/plan/build/debug/ship) → "In progress"; phase Close (design/plan/build/debug) → "In review"; `/bkit-ship` Step 14 → "In review" (never "Done" — the board mirrors the issue, which stays open for human close). GitHub Projects v2 board (`bkit.github.project`; skipped if unset/absent). Linear / Jira no-op (issue state already carries it). |
1102
1106
 
1103
1107
  ### Comment lifecycle
1104
1108
 
@@ -1106,7 +1110,7 @@ new comment per workflow step via tracker MCP. Step 1 = first comment; later ste
1106
1110
 
1107
1111
  ### Issue blockers (`/bkit-build` Step 1)
1108
1112
 
1109
- `/bkit-build` Step 1: tracker `issue-read` → parse blocker relations (Linear: `relations.blocked_by` via `get_issue({ includeRelations: true })`; GitHub: `###### bkit:blocked-by start` … `end` block in the body). Blocker not closed/done → Failure Path `Blocked by {BLOCKER_ID} (state: {BLOCKER_STATE})`. Workflows never write those edges. A human sets them.
1113
+ `/bkit-build` Step 1: tracker `issue-read` → parse blocker relations (GitHub: `###### bkit:blocked-by start` … `end` block in the body; Linear: `relations.blocked_by` via `get_issue({ includeRelations: true })`; Jira: JQL `issue in linkedIssues('{ISSUE_ID}', 'is blocked by') AND statusCategory != Done`). Blocker not closed/done → Failure Path `Blocked by {BLOCKER_ID} (state: {BLOCKER_STATE})`. Workflows never write those edges. A human sets them, directly or by running `@bkit-utility-update-tracker`.
1110
1114
 
1111
1115
  ## GitHub Integration
1112
1116
 
@@ -1269,8 +1273,8 @@ Without `acceptEdits` / wildcard allow surface, every `Bash`, `Edit`, `Write`, M
1269
1273
  <!-- prettier-ignore -->
1270
1274
  | Bucket | Patterns | Purpose |
1271
1275
  | --- | --- | --- |
1272
- | `allow` | `Bash(*)`, `Skill(*)`, `WebSearch`, `mcp__github__*`, `mcp__claude_ai_Linear__*`, `mcp__linear__*` (the `linear` server in `.mcp.json`), `Bash(git push --force-with-lease:*)`, `Read(./.env.example)`, `Read(./\*\*/.env.example)`, `WebFetch(domain:…)` per host in the network allowlist (apex + `*.` wildcard) | Blanket-allow shell, skills, tracker MCP, scoped web fetch. Claude evaluates `deny`, then `ask`, then `allow`: an `allow` row never overrides a matching `ask` or `deny`. `--force-with-lease` passes because no `deny` row matches it, not because of its `allow` row; the `.env.example` rows never fire, since `Read(./.env.*)` asks first. Session-conditional: bucket needs workspace trust; `Bash(*)` dropped in auto mode (§ Cloud sessions). |
1273
- | `ask` | `sudo:*`, `brew install:*`, `(pnpm / npm / bun) publish:*`, `gh repo delete:*`, `gh pr close:*`, `gh release delete:*`; git: `git reset --hard:*`, `git reset \*--hard\*`, `git clean -fd(x):*`, `git clean -\*f\*`, `git filter-branch:*`, `git checkout -- .:*`, `git checkout \*.`, `git checkout \* . \*`, `git restore .:*`, `git restore \*.`, `git restore \* . \*`, `git stash drop:*`, `git rebase -i:*`, `git rebase \* -i( \*)`, `git rebase \*--interactive\*`, `git \* --no-verify( \*)`, `git commit -n\*`, `git commit \* -n( \*)`; `Read(./.env)`, `Read(./.env.\*)`, `Read(./\*\*/.env)`, `Read(./\*\*/.env.\*)`, `Read(./.bkit/.env)` | Per-call human confirmation for destructive ops, hook-skipping commits / pushes and secret reads. The `\*` globs catch the same git commands with flags in another order (`git reset -q --hard`, `git clean -df`); a git global option before the subcommand (`git -C dir reset --hard`) is not matched. The `.env` rows are globs, not an enumeration of known filenames — an enumeration silently drops `.env.ci` / `.env.preview` / anything a consumer invents into `defaultMode`. The recursive `./**/` forms cover monorepo `apps/*` and `packages/*`. Shell reads of secret files (`cat .env`) carry no `Bash(...)` row: a command-text glob cannot tell a read from a mention. |
1276
+ | `allow` | `Bash(*)`, `Skill(*)`, `WebSearch`, `mcp__github__*`, `mcp__linear__*` (the `linear` server in `.mcp.json`), `mcp__jira__*` (the `jira` server), `Bash(git push --force-with-lease:*)`, `Read(./.env.example)`, `Read(./\*\*/.env.example)`, `WebFetch(domain:…)` per host in the network allowlist (apex + `*.` wildcard) | Blanket-allow shell, skills, tracker MCP, scoped web fetch. Claude evaluates `deny`, then `ask`, then `allow`: an `allow` row never overrides a matching `ask` or `deny`. `--force-with-lease` passes because no `deny` row matches it, not because of its `allow` row; the `.env.example` rows never fire, since `Read(./.env.*)` asks first. Session-conditional: bucket needs workspace trust; `Bash(*)` dropped in auto mode (§ Cloud sessions). |
1277
+ | `ask` | `sudo:*`, `brew install:*`, `(pnpm / npm / bun) publish:*`, `gh repo delete:*`, `gh pr close:*`, `gh release delete:*`; git: `git reset --hard:*`, `git reset \*--hard\*`, `git -\* reset \*--hard\*`, `git clean -fd(x):*`, `git clean -\*f\*`, `git filter-branch:*`, `git checkout -- .:*`, `git checkout \*.`, `git checkout \* . \*`, `git restore .:*`, `git restore \*.`, `git restore \* . \*`, `git stash drop:*`, `git stash clear:*`, `git rebase -i:*`, `git rebase \* -i( \*)`, `git rebase \*--interactive\*`, `git \* --no-verify( \*)`, `git commit -n\*`, `git commit \* -n( \*)`; `Read(./.env)`, `Read(./.env.\*)`, `Read(./\*\*/.env)`, `Read(./\*\*/.env.\*)`, `Read(./.bkit/.env)` | Per-call human confirmation for destructive ops, hook-skipping commits / pushes and secret reads. The `\*` globs catch the same git commands with flags in another order (`git reset -q --hard`, `git clean -df`); a git global option before the subcommand (`git -C dir reset --hard`) is not matched. The `.env` rows are globs, not an enumeration of known filenames — an enumeration silently drops `.env.ci` / `.env.preview` / anything a consumer invents into `defaultMode`. The recursive `./**/` forms cover monorepo `apps/*` and `packages/*`. Shell reads of secret files (`cat .env`) carry no `Bash(...)` row: a command-text glob cannot tell a read from a mention. |
1274
1278
  | `deny` | `Bash(rm -rf /\*)`, `Bash(rm -rf ~/\*)`, `Bash(rm -rf $HOME/\*)`, `Bash(chmod -R 777 /:*)`, `Bash(git push --force)`, `Bash(git push --force \*)`, `Bash(git push -f)`, `Bash(git push -f \*)`, `Bash(git push -f\*)`, `Bash(git push \* --force)`, `Bash(git push \* --force \*)`, `Bash(git push \* -f\*)`, `Bash(git push \* +\*)`, `Read(./\*\*/\*.pem)`, `Read(./\*\*/\*.p12)`, `Read(./\*\*/id_rsa)` | Hard-block catastrophic deletes, force-push and private-key reads. Force-push is denied as `--force`, `-f` / an `-f…` cluster, or a `+refspec`, in any argument position. No row is a `--force` prefix: `--force:*` and `--force*` also match `--force-with-lease` and would deny the allowed form. |
1275
1279
 
1276
1280
  Shell `curl` / `wget` are **not** on the Claude `ask` list — they run under `Bash(*)`, with `deny`, the auto-mode classifier, and the advisory `.claude/hooks/bkit-guardrails.cjs` (PreToolUse, matcher `Bash`) as the backstops. Claude rules match a command prefix, not a URL host, so per-domain allows are inexpressible and the only options are blanket-ask or blanket-allow; blanket-ask forces a prompt on **every** shell fetch in **every** mode (a content-scoped `ask` is evaluated before the classifier and beats a matching `allow`), which a cloud session has nobody to answer. `WebFetch(domain:…)` governs the `WebFetch` **tool** only, never `curl` in `Bash`. Cursor gates by parsed URL host (`bkit-guardrails.cjs`), OpenCode via `curl https://{host}/*` allows layered after a `curl *` ask (command-string glob: trailing flags or extra URLs still match, so it narrows rather than blocks). All four run an **allowlisted-host** fetch unprompted; on an **undeclared** host Cursor and OpenCode ask, Claude and Codex emit an advisory instead (Claude to avoid re-adding the prompt, Codex because it cannot prompt).
@@ -1291,7 +1295,7 @@ Auto mode **drops** broad allow rules granting arbitrary code execution — blan
1291
1295
  | `deny` | Blocks | Blocks, before the classifier is consulted |
1292
1296
  | Undeclared network host | Reachable once trusted | Classifier-blocked unless named in `autoMode.environment` |
1293
1297
 
1294
- `.mcp.json` declares `mcpServers.linear.url = https://mcp.linear.app/mcp` and `mcpServers.github.url = https://api.githubcopilot.com/mcp/`. SessionStart hook `bash .claude/hooks/bkit-preflight.sh` runs at every session start.
1298
+ `.mcp.json` declares the wired tracker's server: `mcpServers.github.url = https://api.githubcopilot.com/mcp/`, `mcpServers.linear.url = https://mcp.linear.app/mcp` or `mcpServers.jira.url = https://mcp.atlassian.com/v2/mcp`. SessionStart hook `bash .claude/hooks/bkit-preflight.sh` runs at every session start.
1295
1299
 
1296
1300
  **Anti-pattern:** never `--dangerously-skip-permissions` on host. Sandbox CI containers only.
1297
1301
 
@@ -1350,7 +1354,7 @@ and holds its `bkit` key as `{BKIT}` (plus `repoRoot` as `{REPO_ROOT}`, `outboxR
1350
1354
  | `roadmap` | `fold`, `feature`, `mirror` | `docs/roadmap.md` re-render; append a phase's `kind:"feature"` row then re-render (`--strict`: exit 1 when it did not land); build / debug close: the row in the worktree, then on dev through the throwaway landing |
1351
1355
  | `workstreams` | `parse`, `comment` | design Step 11 advisory comment |
1352
1356
  | `skills` | `prune` | ship Step 7 skill prune |
1353
- | `ci` | `slop`, `prose`, `skip-token` | `slop:delta` gate (CI and `.husky/pre-push`; takes the base sha as `--base=` or its one bare argument), `lint:prose` gate (Vale over `--glob=` files), `.husky/pre-push` skip-CI token check |
1357
+ | `ci` | `slop`, `prose`, `skip-token`, `min-push` | `slop:delta` gate (CI and `.husky/pre-push`; takes the base sha as `--base=` or its one bare argument), `lint:prose` gate (Vale over `--glob=` files), `.husky/pre-push` skip-CI token check, `.husky/pre-push` min-push check (every file the pushed `--ref=`s change matches `bkit.minPushPaths`; exit 0 yes, 1 no, 7 range unreadable) |
1354
1358
  | `setup` | `protect-main` | `main` branch protection requiring `bkit.capstoneJob` |
1355
1359
 
1356
1360
  CI check names come from `package.json` `bkit.capstoneJob` (default `bkit-tests-check`) and `bkit.ciWorkflow` (default `bkit-ci.yml`) — no command hard-codes a check, workflow file, or app folder.
@@ -1364,7 +1368,7 @@ Step 1 of every phase resolves `FID` before taking the lock (the lock path is `l
1364
1368
  1. Session prompt names it — an `FID` slug, a `feat/{FID}` branch, or a `docs/plans/` path carrying it.
1365
1369
  2. Current branch is `feat/{FID}`.
1366
1370
  3. `ISSUE_ID` known → the feature already logged for that issue (`logs/{issue}-*/`, issue lowercased). Two features for one issue → Failure Path listing both; the prompt must name one.
1367
- 4. Mint: `{ISSUE_ID}-{slug}` (Linear id lowercased), slug = title kebab, stopwords stripped, <=3 tokens, ASCII lower. No tracker → `{branch-suffix}-{slug}`.
1371
+ 4. Mint: `{ISSUE_ID}-{slug}` (Linear / Jira key lowercased), slug = title kebab, stopwords stripped, <=3 tokens, ASCII lower. No tracker → `{branch-suffix}-{slug}`.
1368
1372
 
1369
1373
  One FID for all artifacts once set. A workflow never takes `FID` from the newest leftover `.lock` or newest month bucket: on a fresh run with no issue or plan, that silently attached the run to an unrelated feature's logs.
1370
1374
 
@@ -1398,7 +1402,7 @@ bkit issues labels --failed=on|off --label=… → `labels` → `issue-update-fa
1398
1402
  bkit issues labels --label=… → `autoRouteSuffix` → `AUTO_ROUTE_SUFFIX` in the fence that commits or dispatches
1399
1403
  ```
1400
1404
 
1401
- Phase labels (`bkit:design`/`bkit:plan`/`bkit:build`/`bkit:debug`/`bkit:ship`/`bkit:merged`) are mutually exclusive — drop old before adding new. `--phase` also drops every `next:*` label and `bkit:failed` (refuses `--failed=on`), so a started issue carries no stale next-step hint or Failure Path marker. `bkit:failed` skips the drop on its own and lives alongside the phase label. `--board=progress|review` adds the Projects v2 payloads and `linearState`.
1405
+ Phase labels (`bkit:design`/`bkit:plan`/`bkit:build`/`bkit:debug`/`bkit:ship`/`bkit:merged`) are mutually exclusive — drop old before adding new. `--phase` also drops every `next:*` label and `bkit:failed` (refuses `--failed=on`), so a started issue carries no stale next-step hint or Failure Path marker. `bkit:failed` skips the drop on its own and lives alongside the phase label. `--board=progress|review` adds the Projects v2 payloads. `trackerState` = the Linear or Jira state the transition moves to: `progress` on a phase start or `--board=progress`, `review` on `bkit:merged`, `bkit:failed` or `--board=review`, named by package.json `bkit.linear` / `bkit.jira` `progress` / `review` (defaults `started` / `In Review` on Linear, `In Progress` / `In Review` on Jira); null under github and none.
1402
1406
 
1403
1407
  ### Sub-plan loop discovery
1404
1408
 
@@ -1419,9 +1423,10 @@ Each gate is the previous gate plus its own tier, so the name and the value desc
1419
1423
  | Gate | Seeded default | Called by |
1420
1424
  | --- | --- | --- |
1421
1425
  | `bkit:gate:format` | `pnpm lint-staged` | `.husky/pre-commit` |
1426
+ | `bkit:gate:min` | `pnpm format:check && pnpm lint:prose && pnpm slop:delta` | `.husky/pre-push` on a min push |
1422
1427
  | `bkit:gate:static` | `pnpm typecheck && pnpm lint && pnpm format:check && pnpm lint:prose && pnpm slop:delta` | `@bkit-build-plan-execute`, `.husky/pre-push` revert path |
1423
- | `bkit:gate:static-unit` | `pnpm bkit:gate:static && pnpm test` | build Steps 7 + 14, `.husky/pre-push`, `@bkit-build-plan-gaps-remediate`, `@bkit-build-challenge-remediate`, `@bkit-build-challenge-tests`, `@bkit-build-plan-verify`, `@bkit-debug-failure-remediate` |
1424
- | `bkit:gate:static-unit-integration` | not seeded — `pnpm bkit:gate:static-unit && pnpm test:integration` | build Steps 7 + 14 |
1428
+ | `bkit:gate:static-unit` | `pnpm bkit:gate:static && pnpm test` | build Steps 7 + 14, `.husky/pre-push` (no integration gate declared), `@bkit-build-plan-gaps-remediate`, `@bkit-build-challenge-remediate`, `@bkit-build-challenge-tests`, `@bkit-build-plan-verify`, `@bkit-debug-failure-remediate` |
1429
+ | `bkit:gate:static-unit-integration` | not seeded — `pnpm bkit:gate:static-unit && pnpm test:integration` | build Steps 7 + 14, `.husky/pre-push` |
1425
1430
  | `bkit:gate:static-unit-integration-e2e` | not seeded — chains the gate above | debug Step 3 |
1426
1431
  | `bkit:gate:static-unit-integration-e2e-live` | not seeded — chains the gate above | debug Step 3 |
1427
1432
  | `bkit:gate:install-static-unit-build` | `pnpm install --frozen-lockfile && pnpm bkit:gate:static-unit && pnpm build` | `@bkit-ship-conflict-resolve` |
@@ -25,7 +25,7 @@
25
25
  **Else** scan entire session prompt for issue ID — try patterns in order, first match wins:
26
26
 
27
27
  1. `#\d+` → GitHub issue number (e.g. `#123`); strip `#`, set `ISSUE_ID` = `123`
28
- 2. `[A-Z]+-\d+` → prefixed issue ID (e.g. `LIN-123`, `ISSUE-123`, or team-specific prefix)
28
+ 2. `[A-Z][A-Z0-9]*-\d+` → prefixed issue ID (e.g. Linear `LIN-123`, Jira `PROJ-123`, `ISSUE-123`)
29
29
  3. bare `\d+` → numeric fallback (GitHub provider only; ambiguous — prefer `#\d+`)
30
30
 
31
31
  Set `LABELS`, `DESCRIPTION`, `COMMENTS` = empty.
@@ -42,7 +42,7 @@ Scan `LABELS` for commands (Ship, Debug, Build, Plan, Design) → first match
42
42
 
43
43
  ### Step 4 — MCP fallback (labels only)
44
44
 
45
- Only if Steps 2–3 yield no `COMMAND`: read current issue labels via the configured tracker MCP (GitHub: `mcp__github__issue_read({ method: "get_labels", ... })`; Linear: `mcp__linear__get_issue({ id: "{ISSUE_ID}" })`) → scan returned labels → first match → `COMMAND`. Update `LABELS`, `DESCRIPTION`.
45
+ Only if Steps 2–3 yield no `COMMAND`: read current issue labels via the configured tracker MCP (GitHub: `mcp__github__issue_read({ method: "get_labels", ... })`; Linear: `mcp__linear__get_issue({ id: "{ISSUE_ID}" })`; Jira: `mcp__jira__getJiraIssue({ cloudId: "<package.json bkit.jira.site>", issueIdOrKey: "{ISSUE_ID}", view: "evidence" })` → `fields.labels`) → scan returned labels → first match → `COMMAND`. Update `LABELS`, `DESCRIPTION`.
46
46
 
47
47
  ### Step 5 — No match
48
48
 
@@ -96,7 +96,7 @@ Verify only when applicable.
96
96
  - [ ] **Platform Settings:** Hosted platform → Steps 3, 10 — preview overlays, region, CDN cache hit ratio, e.g. Vercel, Netlify, Cloudflare dashboard / API. Fallback: response headers only; settings `Not Checked`.
97
97
  - [ ] **DB Statistics:** Hosted DB → Step 13 — e.g. `pg_stat_statements`, platform performance advisor. Fallback: monitoring spans only.
98
98
  - [ ] **Job Runner:** Background jobs → Steps 12, 13 — run timings and queue lag, e.g. Inngest, Temporal, Sidekiq. Fallback: monitoring spans only.
99
- - [ ] **Tracker:** Follow-ups from previous reports → Step 16 — e.g. `gh`, Linear MCP. Fallback: `Closed Follow-Ups` `Not Checked`.
99
+ - [ ] **Tracker:** Follow-ups from previous reports → Step 16 — via tracker MCP, e.g. GitHub MCP, Linear MCP, Jira MCP; `gh` only as fallback. Fallback: `Closed Follow-Ups` `Not Checked`.
100
100
 
101
101
  ### 🔒 Gate 1: Prerequisites Check
102
102
 
@@ -61,7 +61,8 @@ Board with no stated rule = filing order. Search feature and authorisation bypas
61
61
  | Ranking the next items to work into `docs/roadmap.md` | Roadmap utility | `@bkit-utility-update-roadmap` |
62
62
  | Whether a maintenance check should become a gate | Gate sweep | `bkit-audit-gates` |
63
63
  | Ordering one migration programme's own queue | Project migration map | Project Instructions |
64
- | Writing size, priority, labels, or links; closing, merging, or opening issues | Audit reports only | Plan from this report |
64
+ | Writing size, priority, labels, or links | Tracker writes | `@bkit-utility-update-tracker` |
65
+ | Closing, merging, or opening issues | Owner decision | Plan from this report |
65
66
  | Assignees, start / target dates, numeric estimate | Rules do not read them | Project Instructions |
66
67
 
67
68
  ### Ranking Rules
@@ -110,6 +111,21 @@ Two guards:
110
111
 
111
112
  Finding `CRITICAL`–`LOW` in another audit does not set priority. Two rules do. Severity orders inside `High` only (Step 8).
112
113
 
114
+ ### Size Scale
115
+
116
+ Size work, not body. Long evidence write-up can be one-file fix.
117
+
118
+ <!-- prettier-ignore -->
119
+ | Size | Work |
120
+ | --- | --- |
121
+ | `XS` | One file, one change, plus test |
122
+ | `S` | One surface, a day or less |
123
+ | `M` | Few files in one package, or one full pattern sweep |
124
+ | `L` | Several packages, more than one client, or roughly a week |
125
+ | `XL` | Milestone, full-product inventory, or subsystem not yet built |
126
+
127
+ Multi-client change never sized as one. Standing/umbrella sized for one run, not series. Milestone sized for contents.
128
+
113
129
  ### Pre-Flight / Dependencies
114
130
 
115
131
  **Checkpoint:** Check off all core items. Check conditional items only when applicable. Each item: available → tool and version; missing → fallback, gap in `Not Checked`, fix in `Process Improvements`. Unnamed gap reads as passed. never abort for a missing capability.
@@ -121,9 +137,9 @@ Finding `CRITICAL`–`LOW` in another audit does not set priority. Two rules do.
121
137
  Always verify.
122
138
 
123
139
  - [ ] **Permissions:** Before Step 1 — one cheap read-only call per tool this run uses (every item below, every rule under `Project Instructions` `Permissions`), e.g. `gh run list --limit 1`, one MCP read, one anchor-standard fetch. Blocked / denied (here or in any step) → record call verbatim and narrow allow rule clearing it (e.g. `Bash(gh run list *)`) in `Not Checked`, `Process Improvements`, and `Project Instructions` `Permissions`; run every step the remaining tools allow; work needing blocked call → `Not Checked`. never stop the run for a blocked call; never retry or reword a blocked call to get past it.
124
- - [ ] **Tracker Read:** Steps 2, 5, 10 — every board item with lane, size, and priority, e.g. `gh project item-list`, Linear issues. Fallback: none; unread items `Not Checked`, proposal does not cover them.
125
- - [ ] **Open-Issue List:** Steps 2, 10 — every open issue, every repo / team board draws from, read separately from board, e.g. `gh issue list --state open`, Linear team issues. Fallback: none; membership `Not Checked`, proposal covers board items only.
126
- - [ ] **Issue Bodies:** Steps 3, 4, 6, 8 — title, labels, body, parent, milestone, blocked-by, e.g. `gh issue view`, Linear issue API. Fallback: titles only; each such rank low-confidence in `Judgement Calls`, links from structured fields only.
140
+ - [ ] **Tracker Read:** Steps 2, 5, 10 — every board item with lane, size, and priority, via tracker MCP, e.g. GitHub MCP `projects_list` (project items), Linear MCP `list_issues`, Jira MCP `searchJiraIssuesUsingJql`; `gh` only as fallback. Fallback: none; unread items `Not Checked`, proposal does not cover them.
141
+ - [ ] **Open-Issue List:** Steps 2, 10 — every open issue, every repo / team board draws from, read separately from board, e.g. GitHub MCP `list_issues`, Linear MCP `list_issues` per team, Jira MCP JQL per project. Fallback: none; membership `Not Checked`, proposal covers board items only.
142
+ - [ ] **Issue Bodies:** Steps 3, 4, 6, 8 — title, labels, body, parent, milestone, blocked-by, e.g. GitHub MCP `issue_read`, Linear MCP `get_issue`, Jira MCP `getJiraIssue`. Fallback: titles only; each such rank low-confidence in `Judgement Calls`, links from structured fields only.
127
143
  - [ ] **Web:** Step 11 — fetch anchor standards. Fallback: versions recorded as unread.
128
144
 
129
145
  #### Conditional
@@ -131,7 +147,7 @@ Always verify.
131
147
  Verify only when applicable.
132
148
 
133
149
  - [ ] **Ship Ledger:** Ship outcomes recorded → Step 9 — e.g. `.bkit/stats.jsonl` `outcome` rows. Fallback: size table unchecked against what shipped; say so.
134
- - [ ] **Link API:** Tracker exposes structured blocked-by or parent links → Step 4 — e.g. GitHub dependencies / sub-issues APIs, Linear `relations` / `parent`. Fallback: body text only; say so.
150
+ - [ ] **Link API:** Tracker exposes structured blocked-by or parent links → Step 4 — e.g. GitHub MCP `issue_read` sub-issues / parent, Linear `relations` / `parent`, Jira issue links / `parent`. Fallback: body text only; say so.
135
151
 
136
152
  ### 🔒 Gate 1: Prerequisites Check
137
153
 
@@ -148,7 +164,7 @@ Verify only when applicable.
148
164
  - [ ] **Step 4 — Links:** Per open issue record parent, milestone, blocked-by. Blocked-by: read all three — structured links (`Link API`), body block build gates on (e.g. GitHub `###### bkit:blocked-by start` / `end`), body prose ("blocked by #N", "after #N"). Flag: (1) Parent — child listed in parent body, no link (or reverse); open child, closed parent; open non-standing parent, all children closed → `Judgement Calls`. (2) Milestone — closed / past-due milestone with open issues; child with no or later milestone than parent; body / title names milestone, field empty; open milestone, no open issues. (3) Blocked-by — prose only; structured link vs body block disagree; closed blocker still listed; blocked issue in ready or later lane, blocker open; blocker off-board; cycle. Edges → Step 5 blocker rule, Step 6 parent / child moves. **Done when:** `Links` holds per-kind counts (with / without parent, milestone, blocker) and every flag, or `none`.
149
165
  - [ ] **Step 5 — In Flight:** Three sources: lanes in progress/review; open PRs; issues closed recently (shipped cluster still warm — next issue in cluster cheap). Record launch/milestone target and where written. None → say so; launch-gating keeps Rule 1 band. Count in-progress/in-review; age and last activity (commit, PR, comment). Flag older than service level expectation: 85th-percentile cycle time of issues closed last 90 days, start of work to close. Record how start taken. <20 closed → two weeks, say so. Stuck item lifts parent/children/siblings; list each lift as judgement call. Apply blocker rule to every Step 4 edge. **Done when:** `In Flight` holds counts, ages, target, blocker moves, stuck lifts.
150
166
  - [ ] **Step 6 — Rank:** Apply `Ranking Rules` to every in-scope issue. Record every Rule 1 override (label vs body) and label correction. Record every Rule 2 move with signal and launch target read. Band change since previous report without body/labels/in-flight change → one pass misapplied rule — say which. Maintenance check belonging as gate → `bkit-audit-gates`, not band here. Mini-pass → this step on unsized/unprioritised subset only. Monthly clock → eight-week launch moves and stuck lifts only. **Done when:** `Ranking` lists every override, move, band change.
151
- - [ ] **Step 7 — Size:** Size work, not body. Long evidence write-up can be one-file fix. XS = one file, one change, plus test. S = one surface, a day or less. M = few files one package, or one full pattern sweep. L = several packages, more than one client, or roughly a week. XL = milestone, full-product inventory, or subsystem not yet built. Multi-client change never sized as one. Standing/umbrella sized for one run, not series. Milestone sized for contents. **Done when:** `Sizes` row per in-scope issue.
167
+ - [ ] **Step 7 — Size:** Apply `Size Scale` to every in-scope issue. **Done when:** `Sizes` row per in-scope issue.
152
168
 
153
169
  - [ ] **Step 8 — Order:** Four bands tie issues. Order each ready-lane band; report top ten. Proposal does not invent order field. (1) Inside `High`: blockers of `Urgent` first, then severity. Defect with ledger/audit `CRITICAL` before `HIGH`, both before rest. Severity orders in band; never moves band. (2) Cost of delay ÷ size (WSJF). Score 1–3: user/business value, time-criticality, risk reduced/work unblocked. Sum ÷ size: XS 1, S 2, M 3, L 5, XL 8. Tie → older issue. Simplified WSJF; standard uses modified Fibonacci per part and job size. (3) Demand when any: error-tracker volume, store reviews, analytics, support, previous-product users → raise value score; name source. Empty → say so; do not guess. **Done when:** `Order` holds top ten with scores.
154
170
  - [ ] **Step 9 — Shipped:** Issues closed since previous report → join ship outcome via closing PR (lines changed, duration). Compare with size given. Sizes overlapping heavily in lines/time → size table no longer means what it says; propose change in `Process Improvements`. **Done when:** `Shipped` holds comparison, or no outcomes and say so.