@cbartens/bkit 5.4.0 → 5.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/.bkit/README.md +18 -6
  2. package/.bkit/core/.agents/rules.md +7 -8
  3. package/.bkit/core/.bkit/README.md +17 -5
  4. package/.bkit/core/.bkit/cloud.md +44 -13
  5. package/.bkit/core/.bkit/comparison.md +2 -2
  6. package/.bkit/core/.bkit/install.md +16 -14
  7. package/.bkit/core/.bkit/pipeline.md +3 -1
  8. package/.bkit/core/.bkit/prompts.md +12 -9
  9. package/.bkit/core/.bkit/providers.md +6 -6
  10. package/.bkit/core/.bkit/templates.md +12 -6
  11. package/.bkit/core/.bkit/trackers.md +89 -34
  12. package/.bkit/core/.bkit/workflows.md +42 -38
  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/github.ts +18 -5
  18. package/.bkit/core/engine/checks/after/index.ts +1 -1
  19. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  20. package/.bkit/core/engine/checks/before/env.ts +28 -18
  21. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  22. package/.bkit/core/engine/checks/tips/catalogue.ts +15 -2
  23. package/.bkit/core/engine/cli.ts +7 -5
  24. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  25. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  26. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  27. package/.bkit/core/engine/commands/workflow/issues.ts +35 -16
  28. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  29. package/.bkit/core/engine/commands/workflow/prs.ts +3 -1
  30. package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
  31. package/.bkit/core/engine/commands/workflow/roadmap.ts +5 -1
  32. package/.bkit/core/engine/commands/workflow/steps.ts +2 -2
  33. package/.bkit/core/engine/commands/workflow/workflows.ts +9 -4
  34. package/.bkit/core/engine/install/manifest.ts +31 -10
  35. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  36. package/.bkit/core/engine/install/modules/core.ts +82 -4
  37. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  38. package/.bkit/core/engine/install/write.ts +37 -1
  39. package/.bkit/core/engine/render/trackers.ts +35 -23
  40. package/.bkit/core/engine/shared/egress.ts +6 -0
  41. package/.bkit/core/engine/shared/settings.ts +88 -1
  42. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  43. package/.bkit/core/prompts/bkit-audit-generate.md +42 -12
  44. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  45. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  46. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  47. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  48. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  49. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  50. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  51. package/.bkit/core/prompts/bkit-design-generate.md +2 -1
  52. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  53. package/.bkit/core/prompts/bkit-utility-update-decisions.md +3 -1
  54. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +3 -1
  55. package/.bkit/core/prompts/bkit-utility-update-documentation.md +11 -1
  56. package/.bkit/core/prompts/bkit-utility-update-failures.md +3 -1
  57. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +3 -1
  58. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +9 -2
  59. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  60. package/.bkit/core/workflows/bkit-auto.md +19 -6
  61. package/.bkit/core/workflows/bkit-build.md +59 -17
  62. package/.bkit/core/workflows/bkit-debug.md +64 -20
  63. package/.bkit/core/workflows/bkit-design.md +83 -28
  64. package/.bkit/core/workflows/bkit-plan.md +61 -20
  65. package/.bkit/core/workflows/bkit-ship.md +48 -18
  66. package/.bkit/shared/.bkit/.env.example +8 -0
  67. package/.bkit/shared/.claude/settings.json +3 -1
  68. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  69. package/.bkit/shared/.cursor/mcp.json +11 -4
  70. package/.bkit/shared/.mcp.json +11 -4
  71. package/.bkit/shared/.opencode/opencode.json +2 -0
  72. package/.bkit/shared/docs/deployments.md +15 -4
  73. package/.bkit/shared/docs/security.md +1 -1
  74. package/.bkit/shared/docs/testing.md +3 -3
  75. package/.bkit/templates/.github/renovate.json5 +1 -1
  76. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -54
  77. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  78. package/.bkit/templates/.husky/pre-commit +4 -4
  79. package/.bkit/templates/.husky/pre-push +62 -12
  80. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
  81. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
  82. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  83. package/CHANGELOG.md +37 -1
  84. package/README.md +7 -6
  85. package/dist/checks/after/auth.js +81 -45
  86. package/dist/checks/after/github.js +17 -5
  87. package/dist/checks/after/index.js +1 -1
  88. package/dist/checks/after/tools.js +1 -1
  89. package/dist/checks/before/env.js +24 -17
  90. package/dist/checks/before/mcp.js +4 -2
  91. package/dist/checks/tips/catalogue.js +14 -2
  92. package/dist/cli.js +7 -5
  93. package/dist/commands/ci/ci.js +100 -0
  94. package/dist/commands/install/uninstall.js +42 -0
  95. package/dist/commands/workflow/fids.js +22 -15
  96. package/dist/commands/workflow/issues.js +28 -15
  97. package/dist/commands/workflow/ledgers.js +26 -11
  98. package/dist/commands/workflow/prs.js +3 -1
  99. package/dist/commands/workflow/repo.js +5 -0
  100. package/dist/commands/workflow/roadmap.js +3 -1
  101. package/dist/commands/workflow/steps.js +2 -2
  102. package/dist/commands/workflow/workflows.js +9 -4
  103. package/dist/install/manifest.js +30 -10
  104. package/dist/install/modules/cloud.js +3 -1
  105. package/dist/install/modules/core.js +82 -5
  106. package/dist/install/modules/opencode.js +6 -0
  107. package/dist/install/write.js +26 -2
  108. package/dist/render/trackers.js +34 -20
  109. package/dist/shared/egress.js +6 -0
  110. package/dist/shared/settings.js +39 -0
  111. package/package.json +11 -2
@@ -28,18 +28,25 @@ description: "Build Feature — Autonomous implementation"
28
28
 
29
29
  <!-- bkit:tracker github start -->
30
30
 
31
- > - **Tracker:** GitHub Issues via MCP server `github` (configured in `.mcp.json` `mcpServers.github`). Tool names: `mcp__github__issue_read` (methods `get`, `get_comments`, `get_labels`), `mcp__github__issue_write` (method: `update`), `mcp__github__add_issue_comment`, `mcp__github__list_issues`, `mcp__github__projects_write` (methods `add_project_item` / `update_project_item`), `mcp__github__projects_list` (method `list_project_items`) — needs `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) and `package.json` `bkit.githubProject` config; absent either → board status sync silently skipped. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; all writes best-effort; never gate. **If** failure → retry once after 5s, then continue.
32
- > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive — drop old phase before adding new; a phase start also drops every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
33
- > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__github__add_issue_comment({ owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, body: "{BODY}" })` before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. Comment ID tracking not required.
31
+ > - **Tracker:** GitHub Issues via MCP server `github` (`.mcp.json` `mcpServers.github`). Tools: `mcp__github__issue_read` (method `get` / `get_comments` / `get_labels`), `mcp__github__issue_write` (method `update`), `mcp__github__add_issue_comment`, `mcp__github__list_issues`, `mcp__github__projects_write` (method `add_project_item` / `update_project_item`), `mcp__github__projects_list` (method `list_project_items`); board status sync needs `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) and `package.json` `bkit.githubProject`, absent either → silently skipped. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; writes best-effort, never gate; **If** failure → retry once after 5s → continue.
32
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
33
+ > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__github__add_issue_comment({ owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, body: "{BODY}" })` before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content.
34
34
 
35
35
  <!-- bkit:tracker github end -->
36
36
  <!-- bkit:tracker linear start -->
37
37
 
38
- > - **Tracker:** Linear via MCP server `linear` (configured in `.mcp.json` `mcpServers.linear`). Tool names: `mcp__linear__get_issue`, `mcp__linear__save_issue`, `mcp__linear__save_comment`, `mcp__linear__list_comments`, `mcp__linear__list_issues`. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; all `save_*` writes best-effort; never gate. **If** failure → retry once after 5s, then continue. `save_issue` always includes `id`.
39
- > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive — drop old phase before adding new; a phase start also drops every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
40
- > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id` — creates new comment) before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. No edit-in-place.
38
+ > - **Tracker:** Linear via MCP server `linear` (`.mcp.json` `mcpServers.linear`). Tools: `mcp__linear__get_issue`, `mcp__linear__save_issue`, `mcp__linear__save_issue_label`, `mcp__linear__save_comment`, `mcp__linear__list_comments`, `mcp__linear__list_issues`. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; `save_*` writes best-effort, never gate; **If** failure → retry once after 5s → continue. `save_issue` always includes `id` and is all-or-nothing (one state or label name the team lacks rejects the whole call) → labels and state in separate calls, labels first; create each printed `add` entry first via `save_issue_label({ name })` (`already exists` = done). `Could not find state` / `Could not find label` → log `Unapplied: <state|label> "<name>" not in team`, no retry, continue.
39
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
40
+ > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id`) before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content.
41
41
 
42
42
  <!-- bkit:tracker linear end -->
43
+ <!-- bkit:tracker jira start -->
44
+
45
+ > - **Tracker:** Jira via MCP server `jira` (`.mcp.json` `mcpServers.jira`). Tools: `mcp__jira__getJiraIssue`, `mcp__jira__editJiraIssue`, `mcp__jira__transitionJiraIssue`, `mcp__jira__addOrEditJiraIssueComment`, `mcp__jira__searchJiraIssuesUsingJql`, `mcp__jira__executeRead`; every call passes `cloudId: "{TRACKER_SITE}"`. Assert `{ISSUE_ID}` / `{TRACKER_SITE}` / `{STATE}` / `{LABELS}` non-empty before tool calls; writes best-effort, never gate; **If** failure → retry once after 5s → continue. `getJiraIssue` always passes `view: "evidence"` (other views omit labels). `editJiraIssue` `fields.labels` replaces the whole set → pass full printed `LABELS`; labels and status in separate calls, labels first; never pass `fields` / `update` to `transitionJiraIssue`. Status change: `executeRead({ name: "listJiraIssueTransitions", inputs: { issueIdOrKey } })` → transition whose `to.name` = target status → `transitionJiraIssue({ issueIdOrKey, transitionId })`; none → log `Unapplied: status "<name>" not reachable`, no retry, continue. Comment reads: `executeRead({ name: "listJiraIssueComments", inputs: { issueIdOrKey, maxResults: 100, startAt } })`, oldest first, raise `startAt` while `isLast` is false; page with `appliedContentFormat` = `html` → re-read it one comment per call (`maxResults: 1`).
46
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
47
+ > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__jira__addOrEditJiraIssueComment({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", commentBody: "{BODY}" })` (no `commentId`) before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. Body over 32,767 characters → post as consecutive comments split at line breaks, in order.
48
+
49
+ <!-- bkit:tracker jira end -->
43
50
 
44
51
  > - **Timeouts:** **If** workflow or subagent run > 3600 seconds → **Failure Path**.
45
52
  > - **Limits:** `MAX_VERIFY_ATTEMPT`, `MAX_TEST_ATTEMPT` and `MAX_CHALLENGE_REMEDIATE_ATTEMPT` resolved by name via `bkit counters route --limit=` in fenced routing blocks below.
@@ -56,14 +63,17 @@ description: "Build Feature — Autonomous implementation"
56
63
  "{BKIT}" workflows fail --workflow=build --fid={FID} --month={YYYYMM} --token={LOCK_TOKEN} --max-exceeded {LABEL_FLAGS} --step-number={N} --step-title="{Step Name}" --sub-step={M} --error-file="{OUTBOX_ROOT}/error.md" --stderr-file="{STDERR_FILE}"
57
64
  ```
58
65
  Route:
59
- - **If** exit 0 **or** 5 → hold `handoverNeeded` as `{HANDOVER_NEEDED}`, `labels` as `{LABELS}`, `linearState` as `{LINEAR_STATE}` → step 2.
66
+ - **If** exit 0 **or** 5 → hold `handoverNeeded` as `{HANDOVER_NEEDED}`, `labels` as `{LABELS}`, `trackerState` as `{TRACKER_STATE}` → step 2.
60
67
  - **Else** → step 6.
61
68
  2. <!-- bkit:tracker github start -->
62
69
  `mcp__github__issue_write({ method: "update", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, labels: [{LABELS}] })`.
63
70
  <!-- bkit:tracker github end -->
64
71
  <!-- bkit:tracker linear start -->
65
- `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{LINEAR_STATE}", labels: [{LABELS}] })`.
72
+ `mcp__linear__save_issue_label({ name })` per printed `add` entry → `mcp__linear__save_issue({ id: "{ISSUE_ID}", labels: [{LABELS}] })` → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{TRACKER_STATE}" })`.
66
73
  <!-- bkit:tracker linear end -->
74
+ <!-- bkit:tracker jira start -->
75
+ `mcp__jira__editJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", fields: { labels: [{LABELS}] } })` → move status to `{TRACKER_STATE}` (**Tracker** status change).
76
+ <!-- bkit:tracker jira end -->
67
77
  <!-- bkit:tracker true start -->
68
78
  Post `comment` (when non-null).
69
79
  <!-- bkit:tracker true end -->
@@ -90,15 +100,21 @@ description: "Build Feature — Autonomous implementation"
90
100
  "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" repo info --fetch
91
101
  ```
92
102
  Hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as initial `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`, `behindDev` as `{BEHIND_DEV}`, `divergedAgo` as `{DIVERGED_AGO}`, `bkitAdvisory` as `{BKIT_ADVISORY}`. **If** `BKIT_ADVISORY` != null → emit advisory `[bkit-build] {BKIT_ADVISORY}`.
103
+ <!-- bkit:tracker true start -->
104
+ Hold `trackerTeam` as `{TRACKER_TEAM}`, `trackerProject` as `{TRACKER_PROJECT}`, `trackerSite` as `{TRACKER_SITE}`.
105
+ <!-- bkit:tracker true end -->
93
106
  2. **If** `ISSUE_ID` already set by AGENTS.md → skip. **Else**:
94
107
  <!-- bkit:tracker github start -->
95
108
  Extract from session prompt: `<id>{N}</id>`, `<github_issue>{N}</github_issue>`, `GitHub issue: #{N}`, `ISSUE-{N}`, or bare `#{N}` → numeric N → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
96
109
  <!-- bkit:tracker github end -->
97
110
  <!-- bkit:tracker linear start -->
98
- Extract from session prompt: `<id>{ID}</id>`, `<linear_issue>{ID}</linear_issue>`, `Linear issue: {ID}`, `ISSUE-{ID}`, or scan for `[A-Z]+-\d+` pattern → first match → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
111
+ Extract from session prompt: `<id>{ID}</id>`, `<linear_issue>{ID}</linear_issue>`, `Linear issue: {ID}`, `ISSUE-{ID}`, or `[A-Z]+-\d+` → first match → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
99
112
  <!-- bkit:tracker linear end -->
113
+ <!-- bkit:tracker jira start -->
114
+ Extract from session prompt: `<id>{ID}</id>`, `<jira_issue>{ID}</jira_issue>`, `Jira issue: {ID}`, `ISSUE-{ID}`, a `/browse/{ID}` link, or `[A-Z][A-Z0-9]+-\d+` → first match → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
115
+ <!-- bkit:tracker jira end -->
100
116
  <!-- bkit:tracker false start -->
101
- Scan session prompt for `<id>{ID}</id>` or `ISSUE-{ID}` → first match → `ISSUE_ID`. **If** no `ID` found → set `ISSUE_ID=""` and log `Tracker not wired — proceeding without issue ID.` Workflow continues with FID derived from branch name.
117
+ Scan session prompt for `<id>{ID}</id>` or `ISSUE-{ID}` → first match → `ISSUE_ID`. **If** no `ID` found → set `ISSUE_ID=""`, log `Tracker not wired — proceeding without issue ID.`, continue with FID derived from branch name.
102
118
  <!-- bkit:tracker false end -->
103
119
  3. **If** `LABELS`, `DESCRIPTION`, `COMMENTS` already set by AGENTS.md → sort `COMMENTS` oldest to newest → skip. **Else**:
104
120
  <!-- bkit:tracker github start -->
@@ -107,12 +123,18 @@ description: "Build Feature — Autonomous implementation"
107
123
  <!-- bkit:tracker linear start -->
108
124
  `mcp__linear__get_issue({ id: "{ISSUE_ID}" })` → extract `state.name` → `STATE`; `labels[].name` → `LABELS`; `description` → `DESCRIPTION`; `title` → `TITLE`; `url` → `URL`. Then `mcp__linear__list_comments({ issueId: "{ISSUE_ID}", orderBy: "createdAt desc", limit: 250 })` → sort oldest to newest → `COMMENTS`.
109
125
  <!-- bkit:tracker linear end -->
126
+ <!-- bkit:tracker jira start -->
127
+ `mcp__jira__getJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", view: "evidence" })` → extract `fields.status.name` → `STATE`; `fields.labels` → `LABELS`; `fields.description` → `DESCRIPTION`; `fields.summary` → `TITLE`; `{TRACKER_SITE}/browse/{ISSUE_ID}` → `URL`. Then read comments (**Tracker** comment reads) → `COMMENTS`.
128
+ <!-- bkit:tracker jira end -->
110
129
  4. <!-- bkit:tracker github start -->
111
130
  Parse `{DESCRIPTION}` (already populated by the `issue_read` above) for a `###### bkit:blocked-by start` ... `###### bkit:blocked-by end` block. **If** block absent → no blockers, proceed. **Else** → extract each `- #N` line into `{BLOCKER_ISSUES}` array. For each `N` in `{BLOCKER_ISSUES}` → `mcp__github__issue_read({ method: "get", owner: "{OWNER}", repo: "{REPO}", issue_number: N })` → extract `state`. **If** any blocker `state` != `"closed"` → **Failure Path**.
112
131
  <!-- bkit:tracker github end -->
113
132
  <!-- bkit:tracker linear start -->
114
133
  `mcp__linear__get_issue({ id: "{ISSUE_ID}", includeRelations: true })` → extract `relations` where `type` = `"blocked_by"` → for each entry extract `state.name` as `{BLOCKER_STATE}`. **If** any `{BLOCKER_STATE}` not IN `Done | Cancelled` → **Failure Path**.
115
134
  <!-- bkit:tracker linear end -->
135
+ <!-- bkit:tracker jira start -->
136
+ `mcp__jira__searchJiraIssuesUsingJql({ cloudId: "{TRACKER_SITE}", jql: "issue in linkedIssues('{ISSUE_ID}', 'is blocked by') AND statusCategory != Done", fields: ["summary", "status"] })` → open blockers. **If** any issue returned → **Failure Path**.
137
+ <!-- bkit:tracker jira end -->
116
138
  5. Resolve `FID` — first match wins; never borrow another feature's `FID` from a leftover lock or the newest bucket:
117
139
  1. Session prompt names it — an `FID` slug, a `feat/{FID}` branch, or a path under `docs/plans/{YYYYMM}/` (`{FID}-design.md`, `{FID}-plan.md`, `logs/{FID}/`).
118
140
  2. `BRANCH` = `feat/{FID}` → that `FID`.
@@ -144,20 +166,26 @@ description: "Build Feature — Autonomous implementation"
144
166
  ```bash
145
167
  "{BKIT}" issues labels --phase=build --board=progress --issue={ISSUE_ID} --owner-repo={OWNER_REPO} {LABEL_FLAGS}
146
168
  ```
147
- Hold `labels` as `{LABELS}`, `linearState` as `{LINEAR_STATE}`, `board` as `{BOARD}`.
169
+ Hold `labels` as `{LABELS}`, `trackerState` as `{TRACKER_STATE}`, `board` as `{BOARD}`.
148
170
  <!-- bkit:tracker true end -->
149
171
  <!-- bkit:tracker github start -->
150
172
  `mcp__github__issue_write({ method: "update", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, labels: [{LABELS}] })`.
151
173
  <!-- bkit:tracker github end -->
152
174
  <!-- bkit:tracker linear start -->
153
- `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{LINEAR_STATE}", labels: [{LABELS}] })`.
175
+ `mcp__linear__save_issue_label({ name })` per printed `add` entry → `mcp__linear__save_issue({ id: "{ISSUE_ID}", labels: [{LABELS}] })` → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{TRACKER_STATE}" })`.
154
176
  <!-- bkit:tracker linear end -->
177
+ <!-- bkit:tracker jira start -->
178
+ `mcp__jira__editJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", fields: { labels: [{LABELS}] } })` → move status to `{TRACKER_STATE}` (**Tracker** status change).
179
+ <!-- bkit:tracker jira end -->
155
180
  <!-- bkit:tracker github start -->
156
- **If** `BOARD` = null → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → resolve numeric item id `mcp__github__projects_list({BOARD}.listItems)` → entry whose content issue number == `{ISSUE_ID}` → numeric `id` → `{ITEM_ID}` → set status `mcp__github__projects_write({BOARD}.updateItem + item_id: {ITEM_ID})`.
181
+ **If** `BOARD` = null → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → `mcp__github__projects_list({BOARD}.listItems)` → numeric `id` of entry whose content issue number == `{ISSUE_ID}` → `{ITEM_ID}` → set status `mcp__github__projects_write({BOARD}.updateItem + item_id: {ITEM_ID})`.
157
182
  <!-- bkit:tracker github end -->
158
183
  <!-- bkit:tracker linear start -->
159
184
  No-op (log `Board status carried by issue state — no separate update.`).
160
185
  <!-- bkit:tracker linear end -->
186
+ <!-- bkit:tracker jira start -->
187
+ No-op (log `Board status carried by issue state — no separate update.`).
188
+ <!-- bkit:tracker jira end -->
161
189
  9. <!-- bkit:tracker true start -->
162
190
  Comment:
163
191
  ```bash
@@ -707,6 +735,9 @@ Per-step summary file naming for sub-plan loop steps: `{step}-{SUB_PLAN}-{ATTEMP
707
735
  <!-- bkit:tracker linear start -->
708
736
  `mcp__linear__get_issue({ id: "{ISSUE_ID}" })` → extract `state.name` → `STATE`, `labels[].name` → `LABELS`, `description` → `DESCRIPTION`.
709
737
  <!-- bkit:tracker linear end -->
738
+ <!-- bkit:tracker jira start -->
739
+ `mcp__jira__getJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", view: "evidence" })` → extract `fields.status.name` → `STATE`, `fields.labels` → `LABELS`, `fields.description` → `DESCRIPTION`.
740
+ <!-- bkit:tracker jira end -->
710
741
  ```bash
711
742
  "{BKIT}" roadmap mirror --workflow=build --fid={FID} >/dev/null || exit 1
712
743
  "{BKIT}" workflows close --workflow=build --fid={FID} --month={YYYYMM} --owner-repo={OWNER_REPO} --outbox="{OUTBOX}" --message="chore({FID}): close-workflow" {LABEL_FLAGS} --number=18 --title="Close Workflow & Create PR" --tree={BRANCH} || exit 1
@@ -744,20 +775,26 @@ Per-step summary file naming for sub-plan loop steps: `{step}-{SUB_PLAN}-{ATTEMP
744
775
  ```bash
745
776
  "{BKIT}" issues labels --board=review --issue={ISSUE_ID} --owner-repo={OWNER_REPO}
746
777
  ```
747
- Hold `board` as `{BOARD}`, `linearState` as `{LINEAR_STATE}`.
778
+ Hold `board` as `{BOARD}`, `trackerState` as `{TRACKER_STATE}`.
748
779
  <!-- bkit:tracker true end -->
749
780
  <!-- bkit:tracker github start -->
750
781
  No issue changes.
751
782
  <!-- bkit:tracker github end -->
752
783
  <!-- bkit:tracker linear start -->
753
- Update state only; do not change labels → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{LINEAR_STATE}" })`.
784
+ Update state only; do not change labels → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{TRACKER_STATE}" })`.
754
785
  <!-- bkit:tracker linear end -->
786
+ <!-- bkit:tracker jira start -->
787
+ Update status only; do not change labels → move status to `{TRACKER_STATE}` (**Tracker** status change).
788
+ <!-- bkit:tracker jira end -->
755
789
  <!-- bkit:tracker github start -->
756
- **If** `BOARD` = null → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → resolve numeric item id `mcp__github__projects_list({BOARD}.listItems)` → entry whose content issue number == `{ISSUE_ID}` → numeric `id` → `{ITEM_ID}` → set status `mcp__github__projects_write({BOARD}.updateItem + item_id: {ITEM_ID})`.
790
+ **If** `BOARD` = null → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → `mcp__github__projects_list({BOARD}.listItems)` → numeric `id` of entry whose content issue number == `{ISSUE_ID}` → `{ITEM_ID}` → set status `mcp__github__projects_write({BOARD}.updateItem + item_id: {ITEM_ID})`.
757
791
  <!-- bkit:tracker github end -->
758
792
  <!-- bkit:tracker linear start -->
759
793
  No-op (log `Board status carried by issue state — no separate update.`).
760
794
  <!-- bkit:tracker linear end -->
795
+ <!-- bkit:tracker jira start -->
796
+ No-op (log `Board status carried by issue state — no separate update.`).
797
+ <!-- bkit:tracker jira end -->
761
798
  9. Re-read issue labels post-push:
762
799
  <!-- bkit:tracker github start -->
763
800
  `mcp__github__issue_read({ method: "get", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID} })` → extract `state` (`open` / `closed`) → `STATE`, `labels` → `LABELS`, `body` → `DESCRIPTION`.
@@ -765,6 +802,9 @@ Per-step summary file naming for sub-plan loop steps: `{step}-{SUB_PLAN}-{ATTEMP
765
802
  <!-- bkit:tracker linear start -->
766
803
  `mcp__linear__get_issue({ id: "{ISSUE_ID}" })` → extract `state.name` → `STATE`, `labels[].name` → `LABELS`, `description` → `DESCRIPTION`.
767
804
  <!-- bkit:tracker linear end -->
805
+ <!-- bkit:tracker jira start -->
806
+ `mcp__jira__getJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", view: "evidence" })` → extract `fields.status.name` → `STATE`, `fields.labels` → `LABELS`, `fields.description` → `DESCRIPTION`.
807
+ <!-- bkit:tracker jira end -->
768
808
  <!-- bkit:tracker true start -->
769
809
  After reading issue (`issue-read`): **If** `bkit:auto` not in `LABELS` → kill switch active → terminate workflow normally (current run finishes, no further automation).
770
810
  <!-- bkit:tracker true end -->
@@ -780,8 +820,10 @@ Per-step summary file naming for sub-plan loop steps: `{step}-{SUB_PLAN}-{ATTEMP
780
820
  <!-- bkit:tracker true start -->
781
821
  Append issue link [{ISSUE_ID} {TITLE}]({URL})
782
822
  <!-- bkit:tracker true end -->
823
+ Append a `## Suggested Replies` heading.
783
824
  Append `Would you like me to explain any of this in plain English? Then write 'yes, explain in plain english'.`
784
- Append `{BKIT_TIPS}` under a `## bkit Tips` heading, unless empty.
825
+ Append a `## bkit Tips` heading, unless `{BKIT_TIPS}` is empty.
826
+ Append `{BKIT_TIPS}`, unless empty.
785
827
  13. **If** user requests plain English explanation → restate the summary in plain English; name terms and say what they mean; identifiers stay verbatim; plainness lives in sentences, NOT nouns; do not re-run any step.
786
828
 
787
829
  ### 🔒 Gate 18 — Close Workflow & Create PR
@@ -28,18 +28,25 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
28
28
 
29
29
  <!-- bkit:tracker github start -->
30
30
 
31
- > - **Tracker:** GitHub Issues via MCP server `github` (configured in `.mcp.json` `mcpServers.github`). Tool names: `mcp__github__issue_read` (methods `get`, `get_comments`, `get_labels`), `mcp__github__issue_write` (method: `update`), `mcp__github__add_issue_comment`, `mcp__github__list_issues`, `mcp__github__projects_write` (methods `add_project_item` / `update_project_item`), `mcp__github__projects_list` (method `list_project_items`) — needs `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) and `package.json` `bkit.githubProject` config; absent either → board status sync silently skipped. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; all writes best-effort; never gate. **If** failure → retry once after 5s, then continue.
32
- > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive — drop old phase before adding new; a phase start also drops every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
33
- > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__github__add_issue_comment({ owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, body: "{BODY}" })` before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. Comment ID tracking not required.
31
+ > - **Tracker:** GitHub Issues via MCP server `github` (`.mcp.json` `mcpServers.github`). Tools: `mcp__github__issue_read` (method `get` / `get_comments` / `get_labels`), `mcp__github__issue_write` (method `update`), `mcp__github__add_issue_comment`, `mcp__github__list_issues`, `mcp__github__projects_write` (method `add_project_item` / `update_project_item`), `mcp__github__projects_list` (method `list_project_items`); board status sync needs `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) and `package.json` `bkit.githubProject`, absent either → silently skipped. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; writes best-effort, never gate; **If** failure → retry once after 5s → continue.
32
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
33
+ > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__github__add_issue_comment({ owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, body: "{BODY}" })` before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content.
34
34
 
35
35
  <!-- bkit:tracker github end -->
36
36
  <!-- bkit:tracker linear start -->
37
37
 
38
- > - **Tracker:** Linear via MCP server `linear` (configured in `.mcp.json` `mcpServers.linear`). Tool names: `mcp__linear__get_issue`, `mcp__linear__save_issue`, `mcp__linear__save_comment`, `mcp__linear__list_comments`, `mcp__linear__list_issues`. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; all `save_*` writes best-effort; never gate. **If** failure → retry once after 5s, then continue. `save_issue` always includes `id`.
39
- > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive — drop old phase before adding new; a phase start also drops every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
40
- > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id` — creates new comment) before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. No edit-in-place.
38
+ > - **Tracker:** Linear via MCP server `linear` (`.mcp.json` `mcpServers.linear`). Tools: `mcp__linear__get_issue`, `mcp__linear__save_issue`, `mcp__linear__save_issue_label`, `mcp__linear__save_comment`, `mcp__linear__list_comments`, `mcp__linear__list_issues`. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; `save_*` writes best-effort, never gate; **If** failure → retry once after 5s → continue. `save_issue` always includes `id` and is all-or-nothing (one state or label name the team lacks rejects the whole call) → labels and state in separate calls, labels first; create each printed `add` entry first via `save_issue_label({ name })` (`already exists` = done). `Could not find state` / `Could not find label` → log `Unapplied: <state|label> "<name>" not in team`, no retry, continue.
39
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
40
+ > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id`) before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content.
41
41
 
42
42
  <!-- bkit:tracker linear end -->
43
+ <!-- bkit:tracker jira start -->
44
+
45
+ > - **Tracker:** Jira via MCP server `jira` (`.mcp.json` `mcpServers.jira`). Tools: `mcp__jira__getJiraIssue`, `mcp__jira__editJiraIssue`, `mcp__jira__transitionJiraIssue`, `mcp__jira__addOrEditJiraIssueComment`, `mcp__jira__searchJiraIssuesUsingJql`, `mcp__jira__executeRead`; every call passes `cloudId: "{TRACKER_SITE}"`. Assert `{ISSUE_ID}` / `{TRACKER_SITE}` / `{STATE}` / `{LABELS}` non-empty before tool calls; writes best-effort, never gate; **If** failure → retry once after 5s → continue. `getJiraIssue` always passes `view: "evidence"` (other views omit labels). `editJiraIssue` `fields.labels` replaces the whole set → pass full printed `LABELS`; labels and status in separate calls, labels first; never pass `fields` / `update` to `transitionJiraIssue`. Status change: `executeRead({ name: "listJiraIssueTransitions", inputs: { issueIdOrKey } })` → transition whose `to.name` = target status → `transitionJiraIssue({ issueIdOrKey, transitionId })`; none → log `Unapplied: status "<name>" not reachable`, no retry, continue. Comment reads: `executeRead({ name: "listJiraIssueComments", inputs: { issueIdOrKey, maxResults: 100, startAt } })`, oldest first, raise `startAt` while `isLast` is false; page with `appliedContentFormat` = `html` → re-read it one comment per call (`maxResults: 1`).
46
+ > - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels` computes each transition; MCP writes it.
47
+ > - **Comments:** Post the `comment` a step's `bkit` block prints as a new comment via `mcp__jira__addOrEditJiraIssueComment({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", commentBody: "{BODY}" })` (no `commentId`) before its gate; every gate includes `Issue comment attempted (Step N section)`. never edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. Body over 32,767 characters → post as consecutive comments split at line breaks, in order.
48
+
49
+ <!-- bkit:tracker jira end -->
43
50
 
44
51
  > - **Timeouts:** **If** workflow or subagent run > 3600 seconds → **Failure Path**.
45
52
  > - **Limits:** `MAX_NORMAL_ATTEMPT` and `MAX_SOAK_ATTEMPT` resolved by name via `bkit counters route --limit=` in fenced routing blocks below; `MAX_DEBUG_ATTEMPT` from `bkit counters max`. Counters `{DEBUG_ATTEMPT}` (cross-run; over → fresh `SOAK` run), `{NORMAL_ATTEMPT}` and `{SOAK_ATTEMPT}` (resets on each `SOAK` entry) derive from status.jsonl in fenced blocks below.
@@ -57,14 +64,17 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
57
64
  "{BKIT}" workflows fail --workflow=debug --fid={FID} --month={YYYYMM} --token={LOCK_TOKEN} --max-exceeded {LABEL_FLAGS} --step-number={N} --step-title="{Step Name}" --sub-step={M} --error-file="{OUTBOX_ROOT}/error.md" --stderr-file="{STDERR_FILE}"
58
65
  ```
59
66
  Route:
60
- - **If** exit 0 **or** 5 → hold `handoverNeeded` as `{HANDOVER_NEEDED}`, `labels` as `{LABELS}`, `linearState` as `{LINEAR_STATE}` → step 2.
67
+ - **If** exit 0 **or** 5 → hold `handoverNeeded` as `{HANDOVER_NEEDED}`, `labels` as `{LABELS}`, `trackerState` as `{TRACKER_STATE}` → step 2.
61
68
  - **Else** → step 6.
62
69
  2. <!-- bkit:tracker github start -->
63
70
  `mcp__github__issue_write({ method: "update", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, labels: [{LABELS}] })`.
64
71
  <!-- bkit:tracker github end -->
65
72
  <!-- bkit:tracker linear start -->
66
- `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{LINEAR_STATE}", labels: [{LABELS}] })`.
73
+ `mcp__linear__save_issue_label({ name })` per printed `add` entry → `mcp__linear__save_issue({ id: "{ISSUE_ID}", labels: [{LABELS}] })` → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{TRACKER_STATE}" })`.
67
74
  <!-- bkit:tracker linear end -->
75
+ <!-- bkit:tracker jira start -->
76
+ `mcp__jira__editJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", fields: { labels: [{LABELS}] } })` → move status to `{TRACKER_STATE}` (**Tracker** status change).
77
+ <!-- bkit:tracker jira end -->
68
78
  <!-- bkit:tracker true start -->
69
79
  Post `comment` (when non-null).
70
80
  <!-- bkit:tracker true end -->
@@ -91,15 +101,21 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
91
101
  "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" repo info --fetch
92
102
  ```
93
103
  Hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`, `bkitAdvisory` as `{BKIT_ADVISORY}`. **If** `BKIT_ADVISORY` != null → emit advisory `[bkit-debug] {BKIT_ADVISORY}`.
104
+ <!-- bkit:tracker true start -->
105
+ Hold `trackerTeam` as `{TRACKER_TEAM}`, `trackerProject` as `{TRACKER_PROJECT}`, `trackerSite` as `{TRACKER_SITE}`.
106
+ <!-- bkit:tracker true end -->
94
107
  2. **If** `ISSUE_ID` already set by AGENTS.md → skip. **Else**:
95
108
  <!-- bkit:tracker github start -->
96
109
  Extract from session prompt: `<id>{N}</id>`, `<github_issue>{N}</github_issue>`, `GitHub issue: #{N}`, `ISSUE-{N}`, or bare `#{N}` → numeric N → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
97
110
  <!-- bkit:tracker github end -->
98
111
  <!-- bkit:tracker linear start -->
99
- Extract from session prompt: `<id>{ID}</id>`, `<linear_issue>{ID}</linear_issue>`, `Linear issue: {ID}`, `ISSUE-{ID}`, or scan for `[A-Z]+-\d+` pattern → first match → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
112
+ Extract from session prompt: `<id>{ID}</id>`, `<linear_issue>{ID}</linear_issue>`, `Linear issue: {ID}`, `ISSUE-{ID}`, or `[A-Z]+-\d+` → first match → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
100
113
  <!-- bkit:tracker linear end -->
114
+ <!-- bkit:tracker jira start -->
115
+ Extract from session prompt: `<id>{ID}</id>`, `<jira_issue>{ID}</jira_issue>`, `Jira issue: {ID}`, `ISSUE-{ID}`, a `/browse/{ID}` link, or `[A-Z][A-Z0-9]+-\d+` → first match → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
116
+ <!-- bkit:tracker jira end -->
101
117
  <!-- bkit:tracker false start -->
102
- Scan session prompt for `<id>{ID}</id>` or `ISSUE-{ID}` → first match → `ISSUE_ID`. **If** no `ID` found → set `ISSUE_ID=""` and log `Tracker not wired — proceeding without issue ID.` Workflow continues with FID derived from branch name.
118
+ Scan session prompt for `<id>{ID}</id>` or `ISSUE-{ID}` → first match → `ISSUE_ID`. **If** no `ID` found → set `ISSUE_ID=""`, log `Tracker not wired — proceeding without issue ID.`, continue with FID derived from branch name.
103
119
  <!-- bkit:tracker false end -->
104
120
  3. **If** `LABELS`, `DESCRIPTION`, `COMMENTS` already set by AGENTS.md → sort `COMMENTS` oldest to newest → skip. **Else**:
105
121
  <!-- bkit:tracker github start -->
@@ -108,8 +124,11 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
108
124
  <!-- bkit:tracker linear start -->
109
125
  `mcp__linear__get_issue({ id: "{ISSUE_ID}" })` → extract `state.name` → `STATE`; `labels[].name` → `LABELS`; `description` → `DESCRIPTION`; `title` → `TITLE`; `url` → `URL`. Then `mcp__linear__list_comments({ issueId: "{ISSUE_ID}", orderBy: "createdAt desc", limit: 250 })` → sort oldest to newest → `COMMENTS`.
110
126
  <!-- bkit:tracker linear end -->
127
+ <!-- bkit:tracker jira start -->
128
+ `mcp__jira__getJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", view: "evidence" })` → extract `fields.status.name` → `STATE`; `fields.labels` → `LABELS`; `fields.description` → `DESCRIPTION`; `fields.summary` → `TITLE`; `{TRACKER_SITE}/browse/{ISSUE_ID}` → `URL`. Then read comments (**Tracker** comment reads) → `COMMENTS`.
129
+ <!-- bkit:tracker jira end -->
111
130
  <!-- bkit:tracker false start -->
112
- No tracker wired — set `STATE`, `LABELS`, `DESCRIPTION`, `COMMENTS` all empty; the input artifact is built from the session prompt alone.
131
+ No tracker wired → `STATE`, `LABELS`, `DESCRIPTION`, `COMMENTS` all empty; input artifact built from session prompt alone.
113
132
  <!-- bkit:tracker false end -->
114
133
  4. Resolve `FID` — first match wins; never borrow another feature's `FID` from a leftover lock or the newest bucket:
115
134
  1. Session prompt names it — an `FID` slug, a `feat/{FID}` branch, or a path under `docs/plans/{YYYYMM}/` (`{FID}-design.md`, `{FID}-plan.md`, `logs/{FID}/`).
@@ -129,6 +148,9 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
129
148
  <!-- bkit:tracker linear start -->
130
149
  Lowercase `{ISSUE_ID}`. Format `{issue_id}-{slug}`.
131
150
  <!-- bkit:tracker linear end -->
151
+ <!-- bkit:tracker jira start -->
152
+ Lowercase `{ISSUE_ID}`. Format `{issue_id}-{slug}`.
153
+ <!-- bkit:tracker jira end -->
132
154
  <!-- bkit:tracker false start -->
133
155
  `ISSUE_ID` unset → `{branch-suffix}-{slug}`.
134
156
  <!-- bkit:tracker false end -->
@@ -179,13 +201,16 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
179
201
  - **Else** → false.
180
202
 
181
203
  9. <!-- bkit:tracker github start -->
182
- `mcp__github__issue_write({ method: "update", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, labels: [{LABELS}] })` → **If** `BOARD` = null → log `boardSkipped` → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → resolve numeric item id `mcp__github__projects_list({BOARD}.listItems)` → entry whose content issue number == `{ISSUE_ID}` → numeric `id` → `{ITEM_ID}` → set status `mcp__github__projects_write({BOARD}.updateItem + item_id: {ITEM_ID})`.
204
+ `mcp__github__issue_write({ method: "update", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, labels: [{LABELS}] })` → **If** `BOARD` = null → log `boardSkipped` → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → `mcp__github__projects_list({BOARD}.listItems)` → numeric `id` of entry whose content issue number == `{ISSUE_ID}` → `{ITEM_ID}` → set status `mcp__github__projects_write({BOARD}.updateItem + item_id: {ITEM_ID})`.
183
205
  <!-- bkit:tracker github end -->
184
206
  <!-- bkit:tracker linear start -->
185
- `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{LINEAR_STATE}", labels: [{LABELS}] })`.
207
+ `mcp__linear__save_issue_label({ name })` per printed `add` entry → `mcp__linear__save_issue({ id: "{ISSUE_ID}", labels: [{LABELS}] })` → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{TRACKER_STATE}" })`.
186
208
  <!-- bkit:tracker linear end -->
209
+ <!-- bkit:tracker jira start -->
210
+ `mcp__jira__editJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", fields: { labels: [{LABELS}] } })` → move status to `{TRACKER_STATE}` (**Tracker** status change).
211
+ <!-- bkit:tracker jira end -->
187
212
  <!-- bkit:tracker true start -->
188
- `{LABELS}` = entries of `labels`, `{LINEAR_STATE}` = `linearState`, `{BOARD}` = `board`, printed by (`{LABEL_FLAGS}` = one `--label=<name>` per current `LABELS` entry; sets phase `bkit:debug`, drops prior phase label, `next:*`, `bkit:failed`):
213
+ `{LABELS}` = entries of `labels`, `{TRACKER_STATE}` = `trackerState`, `{BOARD}` = `board`, printed by (`{LABEL_FLAGS}` = one `--label=<name>` per current `LABELS` entry; sets phase `bkit:debug`, drops prior phase label, `next:*`, `bkit:failed`):
189
214
  ```bash
190
215
  "{BKIT}" issues labels --phase=debug --board=progress --issue={ISSUE_ID} --owner-repo={OWNER_REPO} {LABEL_FLAGS}
191
216
  ```
@@ -349,7 +374,7 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
349
374
  ```
350
375
  3. Confirm the local-test artifact Step 3 captured. Do not re-run tests here: `docs/plans/{YYYYMM}/logs/{FID}/context-tests-local-{DEBUG_ATTEMPT}.md` non-empty → narrate `[bkit-debug] local test output CHECKED — captured by Step 3`; **Else** → narrate `[bkit-debug] local test output MISSING — Step 3 captured nothing; treat local-test evidence as unavailable, never as clean`.
351
376
  4. <!-- bkit:tracker github start -->
352
- `{QUERY_NL}` = one natural-language sentence describing failure (error class, failing-test name, exception terms in sentence); never a keyword list → `mcp__github__search_issues({ owner: "{OWNER}", repo: "{REPO}", query: "{QUERY_NL}", perPage: 15 })` → top 15 `items` in rank order; pass no sort parameter, never re-sort, drop any whose `number` == `{ISSUE_ID}`, keep first 10 in rank order → set `RELATED_ISSUES` empty → per hit:
377
+ `{QUERY_NL}` = one natural-language sentence describing failure (error class, failing-test name, exception terms in sentence); never a keyword list → `mcp__github__search_issues({ owner: "{OWNER}", repo: "{REPO}", query: "{QUERY_NL}", perPage: 15 })`; pass no sort parameter, never re-sort, drop any whose `number` == `{ISSUE_ID}`, keep first 10 in rank order → set `RELATED_ISSUES` empty → per hit:
353
378
  - `mcp__github__issue_read({ method: "get", owner: "{OWNER}", repo: "{REPO}", issue_number: {number} })` → write `body` to `{OUTBOX}/related-description.md`.
354
379
  - `mcp__github__issue_read({ method: "get_comments", owner: "{OWNER}", repo: "{REPO}", issue_number: {number} })` → sort oldest to newest → write JSON to `{OUTBOX}/related-comments.json`.
355
380
  - Run the related-text block below → `text` → `RELATED_ISSUE_TEXT`. **If** exit non-zero → append `## #{number} — {title} ({state})` heading plus `Skipped: comments did not parse.` to `RELATED_ISSUES` → next hit.
@@ -357,13 +382,21 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
357
382
  - After the last hit: create `docs/plans/{YYYYMM}/logs/{FID}/context-related-{DEBUG_ATTEMPT}.md` = `RELATED_ISSUES`; 0 hits → `None.`; on call error / timeout → `Search unavailable.`
358
383
  <!-- bkit:tracker github end -->
359
384
  <!-- bkit:tracker linear start -->
360
- `{QUERY_NL}` = one natural-language sentence describing failure (error class, failing-test name, exception terms in sentence); never a keyword list → `mcp__linear__list_issues({ query: "{QUERY_NL}", team: "{LINEAR_TEAM}", limit: 15 })` → results in rank order; pass no `orderBy`, never re-sort, drop any whose `identifier` == `{ISSUE_ID}`, keep first 10 in rank order → set `RELATED_ISSUES` empty → per hit:
385
+ `{QUERY_NL}` = one natural-language sentence describing failure (error class, failing-test name, exception terms in sentence); never a keyword list → `mcp__linear__list_issues({ query: "{QUERY_NL}", team: "{TRACKER_TEAM}", project: "{TRACKER_PROJECT}", limit: 15 })` (omit null `team` / `project`); pass no `orderBy`, never re-sort, drop any whose `identifier` == `{ISSUE_ID}`, keep first 10 in rank order → set `RELATED_ISSUES` empty → per hit:
361
386
  - Write `description` to `{OUTBOX}/related-description.md`.
362
387
  - `mcp__linear__list_comments({ issueId: "{identifier}", orderBy: "createdAt desc", limit: 250 })` → sort oldest to newest → write JSON to `{OUTBOX}/related-comments.json`.
363
388
  - Run the related-text block below → `text` → `RELATED_ISSUE_TEXT`. **If** exit non-zero → append `## {identifier} — {title} ({state.name})` heading plus `Skipped: comments did not parse.` to `RELATED_ISSUES` → next hit.
364
389
  - Append `## {identifier} — {title} ({state.name})` heading plus `RELATED_ISSUE_TEXT` to `RELATED_ISSUES` → discard `RELATED_ISSUE_TEXT` before next hit.
365
390
  - After the last hit: create `docs/plans/{YYYYMM}/logs/{FID}/context-related-{DEBUG_ATTEMPT}.md` = `RELATED_ISSUES`; 0 hits → `None.`; on call error / timeout → `Search unavailable.`
366
391
  <!-- bkit:tracker linear end -->
392
+ <!-- bkit:tracker jira start -->
393
+ `{QUERY_KW}` = 2-4 distinctive terms describing the failure (error class, failing-test name, exception terms); one `text ~` clause per term → `mcp__jira__searchJiraIssuesUsingJql({ cloudId: "{TRACKER_SITE}", jql: "project = {TRACKER_PROJECT} AND (text ~ '<term 1>' OR text ~ '<term 2>' …) AND key != {ISSUE_ID} ORDER BY updated DESC", maxResults: 10, fields: ["summary", "status", "description"] })` (drop `project = {TRACKER_PROJECT} AND` when `{TRACKER_PROJECT}` null) → set `RELATED_ISSUES` empty → per hit:
394
+ - Write `fields.description` to `{OUTBOX}/related-description.md`.
395
+ - Read comments (**Tracker** comment reads) → write JSON to `{OUTBOX}/related-comments.json`.
396
+ - Run the related-text block below → `text` → `RELATED_ISSUE_TEXT`. **If** exit non-zero → append `## {key} — {fields.summary} ({fields.status.name})` heading plus `Skipped: comments did not parse.` to `RELATED_ISSUES` → next hit.
397
+ - Append `## {key} — {fields.summary} ({fields.status.name})` heading plus `RELATED_ISSUE_TEXT` to `RELATED_ISSUES` → discard `RELATED_ISSUE_TEXT` before next hit.
398
+ - After the last hit: create `docs/plans/{YYYYMM}/logs/{FID}/context-related-{DEBUG_ATTEMPT}.md` = `RELATED_ISSUES`; 0 hits → `None.`; on call error / timeout → `Search unavailable.`
399
+ <!-- bkit:tracker jira end -->
367
400
  <!-- bkit:tracker true start -->
368
401
  Related-text block:
369
402
  ```bash
@@ -577,6 +610,9 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
577
610
  <!-- bkit:tracker linear start -->
578
611
  `mcp__linear__get_issue({ id: "{ISSUE_ID}" })` → extract `state.name` → `STATE`, `labels[].name` → `LABELS`, `description` → `DESCRIPTION`.
579
612
  <!-- bkit:tracker linear end -->
613
+ <!-- bkit:tracker jira start -->
614
+ `mcp__jira__getJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", view: "evidence" })` → extract `fields.status.name` → `STATE`, `fields.labels` → `LABELS`, `fields.description` → `DESCRIPTION`.
615
+ <!-- bkit:tracker jira end -->
580
616
  ```bash
581
617
  PR_OPEN="{PR_OPEN}"
582
618
  "{BKIT}" status meta --file="{STATUS}" --workflow=debug --push-mode={PUSH_MODE} >/dev/null || exit 1
@@ -622,13 +658,16 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
622
658
  - **If** exit 81 or 80 → **CI wait turn-loop** → re-run this block with `{CI_REENTRY}`.
623
659
  - **Else** (1 unresolved verdict, 4 skip token in the pushed body, 5 / 6 / other) → **Failure Path**.
624
660
  8. <!-- bkit:tracker github start -->
625
- No issue label changes. **If** `BOARD` = null → log `boardSkipped` → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → resolve numeric item id `mcp__github__projects_list({BOARD}.listItems)` → entry whose content issue number == `{ISSUE_ID}` → numeric `id` → `{ITEM_ID}` → set status `mcp__github__projects_write({BOARD}.updateItem + item_id: {ITEM_ID})`.
661
+ No issue label changes. **If** `BOARD` = null → log `boardSkipped` → skip. **Else** → ensure on board `mcp__github__projects_write({BOARD}.addItem)` → `mcp__github__projects_list({BOARD}.listItems)` → numeric `id` of entry whose content issue number == `{ISSUE_ID}` → `{ITEM_ID}` → set status `mcp__github__projects_write({BOARD}.updateItem + item_id: {ITEM_ID})`.
626
662
  <!-- bkit:tracker github end -->
627
663
  <!-- bkit:tracker linear start -->
628
- Update state only; do not change labels → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{LINEAR_STATE}" })`.
664
+ Update state only; do not change labels → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{TRACKER_STATE}" })`.
629
665
  <!-- bkit:tracker linear end -->
666
+ <!-- bkit:tracker jira start -->
667
+ Update status only; do not change labels → move status to `{TRACKER_STATE}` (**Tracker** status change).
668
+ <!-- bkit:tracker jira end -->
630
669
  <!-- bkit:tracker true start -->
631
- `{LINEAR_STATE}` = `linearState`, `{BOARD}` = `board`, printed by:
670
+ `{TRACKER_STATE}` = `trackerState`, `{BOARD}` = `board`, printed by:
632
671
  ```bash
633
672
  "{BKIT}" issues labels --board=review --issue={ISSUE_ID} --owner-repo={OWNER_REPO}
634
673
  ```
@@ -640,6 +679,9 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
640
679
  <!-- bkit:tracker linear start -->
641
680
  `mcp__linear__get_issue({ id: "{ISSUE_ID}" })` → extract `state.name` → `STATE`, `labels[].name` → `LABELS`, `description` → `DESCRIPTION`.
642
681
  <!-- bkit:tracker linear end -->
682
+ <!-- bkit:tracker jira start -->
683
+ `mcp__jira__getJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", view: "evidence" })` → extract `fields.status.name` → `STATE`, `fields.labels` → `LABELS`, `fields.description` → `DESCRIPTION`.
684
+ <!-- bkit:tracker jira end -->
643
685
  <!-- bkit:tracker true start -->
644
686
  After reading issue (`issue-read`): **If** `bkit:auto` not in `LABELS` → kill switch active → terminate workflow normally (current run finishes, no further automation).
645
687
  <!-- bkit:tracker true end -->
@@ -658,8 +700,10 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
658
700
  <!-- bkit:tracker true start -->
659
701
  Append issue link [{ISSUE_ID} {TITLE}]({URL})
660
702
  <!-- bkit:tracker true end -->
703
+ Append a `## Suggested Replies` heading.
661
704
  Append `Would you like me to explain any of this in plain English? Then write 'yes, explain in plain english'.`
662
- Append `{BKIT_TIPS}` under a `## bkit Tips` heading, unless empty.
705
+ Append a `## bkit Tips` heading, unless `{BKIT_TIPS}` is empty.
706
+ Append `{BKIT_TIPS}`, unless empty.
663
707
  13. **If** user requests plain English explanation → restate the summary in plain English; name terms and say what they mean; identifiers stay verbatim; plainness lives in sentences, NOT nouns; do not re-run any step.
664
708
 
665
709
  ### 🔒 Gate 11 — Close Workflow