@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
@@ -3,7 +3,7 @@
3
3
  {{BKIT_MANAGED_MARKER}}
4
4
 
5
5
  > [!CAUTION]
6
- > **Purpose:** Reference for inline tracker-block model in `.bkit/core/workflows/bkit-*.md` and `.bkit/core/prompts/bkit-*.md`. **Not consumed by installer** — no `trackers.md` substitution. Per-tracker call bodies (`github` / `linear` / `none`) live INLINE at each workflow call site; this file documents marker contract, cross-cutting per-tracker conventions, and the issue shapes workflows read (§ Issue shapes).
6
+ > **Purpose:** Reference for inline tracker-block model in `.bkit/core/workflows/bkit-*.md` and `.bkit/core/prompts/bkit-*.md`. **Not consumed by installer** — no `trackers.md` substitution. Per-tracker call bodies (`github` / `linear` / `jira`, plus `false` for no tracker) live INLINE at each workflow call site; this file documents marker contract, cross-cutting per-tracker conventions, and the issue shapes workflows read (§ Issue shapes).
7
7
  >
8
8
  > **Rules:**
9
9
  >
@@ -11,18 +11,18 @@
11
11
  > - Describe current state / rules, not reasons / history; state what to do, not why.
12
12
  > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another. Label semantics live in `.bkit/workflows.md` § Tracker Integration; this file is the marker contract + operational per-tracker reference.
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
- > - Three trackers: `github` (default), `linear` (opt-in), `none` (no tracker wired).
15
- > - New tracker (Jira, etc.): add enum to `.bkit/core/engine/install/manifest.ts`; document MCP under `mcpServers.<name>` in `.bkit/shared/.mcp.json` and `.bkit/shared/.cursor/mcp.json`; add `<!-- bkit:tracker <name> -->` block alongside `github`/`linear` at every call site (extend pair resolver in `.bkit/core/engine/render/trackers.ts`). No `none` marker — no-tracker content is `false`.
14
+ > - Four values: `github`, `linear`, `jira`, `none` (no tracker wired, the default).
15
+ > - New tracker: add enum to `.bkit/core/engine/install/manifest.ts`; document MCP under `mcpServers.<name>` in `.bkit/shared/.mcp.json` and `.bkit/shared/.cursor/mcp.json`; add `<!-- bkit:tracker <name> -->` block after the last tracker block at every call site (extend `GROUP_RE` in `.bkit/core/engine/render/trackers.ts`). No `none` marker — no-tracker content is `false`.
16
16
 
17
17
  ## Marker contract
18
18
 
19
19
  Workflow and prompt sources carry wired tracker variants inline. Installer reads `bkit.issueTracker` from consumer manifest, resolves markers when mirroring `.bkit/core/workflows/bkit-*.md` to every host's commands / skills and `.bkit/core/prompts/bkit-*.md` to every host's agents (`.bkit/core/engine/render/trackers.ts`). Mirrors clean — no markers survive.
20
20
 
21
- Prompt frontmatter `tools:` lists: every marker must be a YAML comment (` # <!-- bkit:tracker github start -->`) — a bare `<!--` line is invalid YAML; installer strips the `# ` with the marker. A pair inside the YAML list must end with a `false` block, and every block (incl. `false`) must hold at least one list item — the `none` stub and an empty block both break the YAML. `bkit-utility-update-roadmap` carries `- Bash`, `bkit-audit-generate` `- WebSearch`, in all three blocks for this.
21
+ Prompt frontmatter `tools:` lists: every marker must be a YAML comment (` # <!-- bkit:tracker github start -->`) — a bare `<!--` line is invalid YAML; installer strips the `# ` with the marker. A group inside the YAML list must end with a `false` block, and every block (incl. `false`) must hold at least one list item — the `none` stub and an empty block both break the YAML. `bkit-utility-update-roadmap` and `bkit-utility-update-tracker` carry `- Bash`, `bkit-audit-generate` `- WebSearch`, in every block for this.
22
22
 
23
- ### Per-tracker pair (`github` / `linear`)
23
+ ### Per-tracker group (`github` / `linear` / `jira`)
24
24
 
25
- Every call site = consecutive `github` → `linear` pair, optionally trailing `false` block (substantive no-tracker rendering). Without `false`, no-tracker rendering = generic message at resolution time.
25
+ Every call site = consecutive `github` → `linear` → `jira` group, optionally trailing `false` block (substantive no-tracker rendering). Without `false`, no-tracker rendering = generic message at resolution time.
26
26
 
27
27
  ```text
28
28
  <!-- bkit:tracker github start -->
@@ -31,16 +31,19 @@ mcp__github__… call
31
31
  <!-- bkit:tracker linear start -->
32
32
  mcp__linear__… call
33
33
  <!-- bkit:tracker linear end -->
34
+ <!-- bkit:tracker jira start -->
35
+ mcp__jira__… call
36
+ <!-- bkit:tracker jira end -->
34
37
  ```
35
38
 
36
- Resolution: `github` → github block; `linear` → linear block; `none` → pair's trailing `false` block if present, else **`_No tracker connected, skip step._`**. List-number prefix (`3. `) before pair preserved on kept block / stub. Lone `github` or `linear` (no partner) = orphan.
39
+ Resolution: each tracker → its own block; `none` → group's trailing `false` block if present, else **`_No tracker connected, skip step._`**. List-number prefix (`3. `) before group preserved on kept block / stub. A block outside a full group = orphan; under `jira`, a group with no `jira` block stays whole, so its markers surface as orphans.
37
40
 
38
41
  ### Conditional blocks (`bkit:tracker true` / `bkit:tracker false`)
39
42
 
40
43
  Boolean tracker-presence gates for tracker-agnostic content. only no-tracker markers — no `none` marker.
41
44
 
42
- - `<!-- bkit:tracker true start/end -->` — kept when tracker connected (`github` or `linear`); **removed entirely under `none`** (no stub). Shared content e.g. comment `{BODY}` fence identical for github/linear.
43
- - `<!-- bkit:tracker false start/end -->` — kept only under `none`; removed when wired. Substantive no-tracker behaviour (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`). `false` directly after `github`/`linear` pair = pair's `none` rendering; standalone `false` resolved on its own.
45
+ - `<!-- bkit:tracker true start/end -->` — kept when tracker connected (`github`, `linear` or `jira`); **removed entirely under `none`** (no stub). Shared content e.g. comment `{BODY}` fence identical for every tracker.
46
+ - `<!-- bkit:tracker false start/end -->` — kept only under `none`; removed when wired. Substantive no-tracker behaviour (`issue-id-extraction`, `fid-format`, `pr-body-marker`, `pr-body-metadata`). `false` directly after a tracker group = group's `none` rendering; standalone `false` resolved on its own.
44
47
 
45
48
  ```text
46
49
  <!-- bkit:tracker true start -->
@@ -48,13 +51,13 @@ Boolean tracker-presence gates for tracker-agnostic content. only no-tracker mar
48
51
  <!-- bkit:tracker true end -->
49
52
  ```
50
53
 
51
- Conditionals resolved after pair pass — pair nested inside kept `true` resolves first. Removed block consumes leading newline + indentation (no blank gap). Unbalanced `start`/`end` = orphan.
54
+ Conditionals resolved after group pass — group nested inside kept `true` resolves first. Removed block consumes leading newline + indentation (no blank gap). Unbalanced `start`/`end` = orphan.
52
55
 
53
56
  **Numbered-step rule:** never wrap numbered list item's NUMBER inside `true` block — under `none` whole item vanishes → numbering gap (`1, 6, 7`). Numbered step with tracker-only body: keep `N.` outside markers; pair `true` body with trailing `false` stub. Put `false` on same line as `true end`, single leading space before stub → inline (`N. _stub_`) not dangling continuation:
54
57
 
55
58
  ```text
56
59
  N. <!-- bkit:tracker true start -->
57
- … tracker-only body (github/linear pairs allowed inside) …
60
+ … tracker-only body (tracker groups allowed inside) …
58
61
  <!-- bkit:tracker true end --><!-- bkit:tracker false start --> _No tracker connected, skip step._<!-- bkit:tracker false end -->
59
62
  ```
60
63
 
@@ -62,26 +65,26 @@ Renders `N. <body>` when wired, `N. _No tracker connected, skip step._` under `n
62
65
 
63
66
  ## Interaction catalog
64
67
 
65
- Per-tracker call sites referenced across `.bkit/workflows.md` by these names. Each = inline `github`/`linear` pair; authoritative bodies inline in workflows. `none` column: most sites collapse to generic `_No tracker connected, skip step._`; few carry substantive trailing `false` block (shown) for no-tracker function.
68
+ Per-tracker call sites referenced across `.bkit/workflows.md` by these names. Each = inline `github` / `linear` / `jira` group; authoritative bodies inline in workflows. `none` column: most sites collapse to generic `_No tracker connected, skip step._`; few carry substantive trailing `false` block (shown) for no-tracker function.
66
69
 
67
70
  <!-- prettier-ignore -->
68
- | Interaction | Purpose | github | linear | none |
69
- | --- | --- | --- | --- | --- |
70
- | `rule-block` | CAUTION-block tracker/labels/comments rules | rules prose | rules prose | "not configured" stub |
71
- | `issue-id-extraction` | Step 1 `ISSUE_ID` resolution. No match → stop. Never creates an issue | session prompt scan; no match → stop | session prompt scan; no match → stop | scan session prompt; else `ISSUE_ID=""` |
72
- | `fid-format` | FID slug regex assertion | `^[0-9]+-[a-z0-9-]+$` | `^[a-z]+-[0-9]+-[a-z0-9-]+$` | no strict assert |
73
- | `issue-read` | Read state + labels + body + comments | `issue_read` `get` / `get_comments` | `get_issue` / `list_comments` | skip (vars empty) |
74
- | `issue-scan` | Bounded related-issue scan at design/plan/debug entry — writes each hit's body + comments under a `## #{number} — {title} ({state})` heading to a file (advisory, top 10, never gates); broad keyword search in title+body, all states | `search_issues` for ranking only + per-hit `issue_read` `get` / `get_comments` | `list_issues` + per-hit `list_comments` | skip stub (no scan) |
75
- | `issue-update-phase` | Step 1: set phase label (`bkit:debug` included; drops `next:*`, `bkit:failed`) + active state | `issue_write` labels | `save_issue` state+labels | skip |
76
- | `issue-update-review` | phase Close hand-off (non-terminal) | no-op (label carries) | `save_issue` In Review | skip |
77
- | `issue-update-failed` | Failure Path additive `bkit:failed` | `issue_write` labels | `save_issue` In Review | skip |
78
- | `issue-update-merged` | Ship terminal — `bkit:merged` + In Review (issue left open; human closes) | `issue_write` `bkit:merged` (no close) | `save_issue` In Review | skip |
79
- | `issue-update-status` | Projects v2 board status (best-effort) | `projects_write` add/update item | no-op (state carries) | skip |
80
- | `comment-post-step` | new comment per workflow step | `add_issue_comment` | `save_comment` | skip |
81
- | `issue-blockers-check` | Gate on open blockers | parse body marker → read states | `get_issue` relations | skip |
82
- | `kill-switch-check` | Terminate if `bkit:auto` absent | label check | label check | inactive |
83
- | `pr-body-metadata` | Parse PR-body issue/FID marker | `pull_request_read` + parse | same (GitHub PR) | FID-only, no fail-closed |
84
- | `pr-body-marker` | Literal PR-body marker line | `<!-- bkit:issue=#{ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:issue={ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:fid={FID} -->` |
71
+ | Interaction | Purpose | github | linear | jira | none |
72
+ | --- | --- | --- | --- | --- | --- |
73
+ | `rule-block` | CAUTION-block tracker/labels/comments rules | rules prose | rules prose | rules prose | "not configured" stub |
74
+ | `issue-id-extraction` | Step 1 `ISSUE_ID` resolution. No match → stop. Never creates an issue | session prompt scan; no match → stop | session prompt scan; no match → stop | session prompt scan (incl. `/browse/{KEY}` links); no match → stop | scan session prompt; else `ISSUE_ID=""` |
75
+ | `fid-format` | FID slug regex assertion | `^[0-9]+-[a-z0-9-]+$` | `^[a-z]+-[0-9]+-[a-z0-9-]+$` | `^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$` | no strict assert |
76
+ | `issue-read` | Read state + labels + body + comments | `issue_read` `get` / `get_comments` | `get_issue` / `list_comments` | `getJiraIssue` `view: "evidence"` / `executeRead` `listJiraIssueComments` | skip (vars empty) |
77
+ | `issue-scan` | Bounded related-issue scan at design/plan/debug entry — writes each hit's body + comments under a `## #{number} — {title} ({state})` heading to a file (advisory, top 10, never gates); broad keyword search in title+body, all states | `search_issues` for ranking only + per-hit `issue_read` `get` / `get_comments` | `list_issues` + per-hit `list_comments` | `searchJiraIssuesUsingJql` (`text ~` per keyword, inside `bkit.jira.project`) + per-hit `listJiraIssueComments` | skip stub (no scan) |
78
+ | `issue-update-phase` | Step 1: set phase label (`bkit:debug` included; drops `next:*`, `bkit:failed`) + active state | `issue_write` labels | `save_issue_label` per new label, then `save_issue` labels, then `save_issue` state `bkit.linear.progress` | `editJiraIssue` full label set, then transition to `bkit.jira.progress` | skip |
79
+ | `issue-update-review` | phase Close hand-off (non-terminal) | no-op (label carries) | `save_issue` state `bkit.linear.review` | transition to `bkit.jira.review` | skip |
80
+ | `issue-update-failed` | Failure Path additive `bkit:failed` | `issue_write` labels | `save_issue_label` per new label, then `save_issue` labels, then `save_issue` state `bkit.linear.review` | `editJiraIssue` full label set, then transition to `bkit.jira.review` | skip |
81
+ | `issue-update-merged` | Ship terminal — `bkit:merged` + In Review (issue left open; human closes) | `issue_write` `bkit:merged` (no close) | `save_issue_label` per new label, then `save_issue` labels, then `save_issue` state `bkit.linear.review` | `editJiraIssue` full label set, then transition to `bkit.jira.review` | skip |
82
+ | `issue-update-status` | Projects v2 board status (best-effort) | `projects_write` add/update item | no-op (state carries) | no-op (status carries) | skip |
83
+ | `comment-post-step` | new comment per workflow step | `add_issue_comment` | `save_comment` | `addOrEditJiraIssueComment` | skip |
84
+ | `issue-blockers-check` | Gate on open blockers | parse body marker → read states | `get_issue` relations | JQL `linkedIssues(KEY, "is blocked by") AND statusCategory != Done` | skip |
85
+ | `kill-switch-check` | Terminate if `bkit:auto` absent | label check | label check | label check | inactive |
86
+ | `pr-body-metadata` | Parse PR-body issue/FID marker | `pull_request_read` + parse | same (GitHub PR) | same (GitHub PR) | FID-only, no fail-closed |
87
+ | `pr-body-marker` | Literal PR-body marker line | `<!-- bkit:issue=#{ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:issue={ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:issue={ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:fid={FID} -->` |
85
88
 
86
89
  Phase-label set + additive-label semantics: `.bkit/workflows.md` § Tracker Integration.
87
90
 
@@ -116,25 +119,86 @@ Workflows read issue body + comments (`bkit issues text`), never title (title
116
119
  | --- | --- | --- |
117
120
  | `**Parent design:** [{FID}-design.md](https://github.com/{OWNER_REPO}/blob/dev/docs/plans/{YYYYMM}/{FID}-design.md)` | plan Step 1 | sets `PARENT_FID` → design = spec source; absent → the design made on the same issue (`bkit fids design`) |
118
121
  | `**Audit reports:** docs/audits/{YYYYMM}/{slug}.md (findings {ids})` | plan Step 1 | each path → `AUDIT_PATHS`; path not a file → Failure Path |
119
- | `###### bkit:blocked-by start` · `- #{N}` per line · `###### bkit:blocked-by end` | build `issue-blockers-check` (github; linear → native relations) | any listed issue open → build stops |
122
+ | `###### bkit:blocked-by start` · `- #{N}` per line · `###### bkit:blocked-by end` | build `issue-blockers-check` (github; linear / jira → native relations) | any listed issue open → build stops |
120
123
  | `###### bkit:ignore-earlier` | `bkit issues text` | drops all earlier content; human-placed only |
121
124
  | `###### bkit:generated` (comment first line) | `bkit issues text` | comment dropped from input |
122
125
 
123
- **References** — exact strings agents can search: issue `#N — {title}` (linear `TEAM-N — {title}`); doc `{path} § {section}`; ledger row `docs/{ledger}.jsonl` key `` `{key}` ``. Labels: type label (`enhancement` / `bug`) + one `next:*` (`.agents/rules.md` § Tracker next labels); never phase or `bkit:*` labels — workflows set them (`.bkit/workflows.md` § Tracker Integration).
126
+ **References** — exact strings agents can search: issue `#N — {title}` (linear / jira `KEY-N — {title}`); doc `{path} § {section}`; ledger row `docs/{ledger}.jsonl` key `` `{key}` ``. Labels: type label (github `enhancement` / `bug`; linear the team's own, default `Improvement` / `Feature` / `Bug`; jira none — issue type carries type) + one `next:*` (`.agents/rules.md` § Tracker next labels); never phase or `bkit:*` labels — workflows set them (`.bkit/workflows.md` § Tracker Integration).
124
127
 
125
128
  **Drafting from bkit output** (suggest only; file after human confirmation):
126
129
 
127
130
  <!-- prettier-ignore -->
128
131
  | Source | Shape | Carry |
129
132
  | --- | --- | --- |
130
- | audit `Suggested Issues` row | by `Next Step`: `/bkit-design` → idea; `/bkit-plan`, `/bkit-build`, `build:lite` → change; `/bkit-debug`, `debug:lite` → bug; `manual` → plain task | `**Audit reports:**` line with row's finding IDs |
131
- | design `Suggested Workstreams` (2+; design summary asks) | title = workstream name; body = its scope, spec left to design; filed in `Requires` order | `**Parent design:**` line; blocked-by block = issues filed for its `Requires` (linear → `blockedBy` relation) |
133
+ | audit run, tracker wired, no open audit parent for its template (`Parent: missing`) | audit parent (below) | template path line |
134
+ | audit `Suggested Issues` row | by `Next Step`: `/bkit-design` → idea; `/bkit-plan`, `/bkit-build`, `build:lite` → change; `/bkit-debug`, `debug:lite` → bug; `manual` → plain task | `**Audit reports:**` line with row's finding IDs; sub-issue of the template's audit parent (linear → `parentId`; jira → `parent`) |
135
+ | design `Suggested Workstreams` (2+; design summary asks) | title = workstream name; body = its scope, spec left to design; filed in `Requires` order | `**Parent design:**` line; blocked-by block = issues filed for its `Requires` (linear → `blockedBy` relation; jira → `Blocks` link, `inwardIssue` = blocker) |
132
136
  | roadmap item with no issue (ledger row, audit candidate) | by recommended command, as audit row | ledger `key` / report path in References |
133
137
 
138
+ **Audit parent** — one standing issue per audit template, shared by every run of that template; never one per run, never one across templates.
139
+
140
+ <!-- prettier-ignore -->
141
+ | Field | Value |
142
+ | --- | --- |
143
+ | Title | template H1 (`Security Audit`) |
144
+ | Body | names `docs/templates/bkit-audit-{slug}.md` verbatim (`@bkit-audit-generate` finds the parent by this path); run line `@bkit-audit-generate docs/templates/bkit-audit-{slug}.md #{N}` (linear / jira `KEY-N`); report path `docs/audits/{YYYYMM}/{slug}.md` |
145
+ | Labels | project's own (e.g. `maintenance`); no workflow, `next:*` or `bkit:*` label — it runs no workflow |
146
+ | Milestone | one milestone holding every audit parent, when the project keeps one |
147
+ | State | stays open; runs never close it; filed issues reference it as `#N — {title}`, never `Closes #N` |
148
+ | Children | every issue filed from its runs' `Suggested Issues`, always (github sub-issues; linear `parentId`; jira `parent`) |
149
+ | Comments | one `### Audit Summary: {slug}` comment per run — posted by the run when named or found; a newly filed parent gets the run's saved `parent-comment.md` as its first comment |
150
+
134
151
  ## github — Projects v2 board (optional)
135
152
 
136
- `issue-update-status` reads `package.json` `bkit.githubProject` = `{ owner (org login), number, statusFieldId, progressOptionId, reviewOptionId, doneOptionId }` (non-secret, committed). Absent → board sync skipped (best-effort, never gates). Discover ids once: `gh api /orgs/{owner}/projectsV2/{number}/fields --jq '.[] | select(.name=="Status")'` (Status field numeric `id` → `statusFieldId`; each option raw `id` → option id, e.g. `47fc9ee4`; `PVTSSF_…` node id from `gh project field-list` is not field id — `projects_write` rejects it). Requires `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) + `BKIT_GH_TOKEN` org Projects R/W. Org-owned boards only — fine-grained PATs cannot reach user-owned projects, nor span orgs; use a classic PAT with `project` when the token must cover more than one owner. `value` = single-select **option id**, not option name. Failure → retry once after 5s, then continue. `doneOptionId` is **reserved and never written** — ship terminal sets `reviewOptionId`, and a human moves the item to Done on acceptance (§ `issue-update-merged` in `.bkit/workflows.md`).
153
+ `issue-update-status` reads `package.json` `bkit.github` = `{ project, progress, review }` (non-secret, committed), same shape as `bkit.linear` / `bkit.jira`:
154
+
155
+ <!-- prettier-ignore -->
156
+ | Key | Value | Default |
157
+ | --- | --- | --- |
158
+ | `project` | Board URL as the browser shows it: `https://github.com/orgs/<org>/projects/<n>` or `https://github.com/users/<login>/projects/<n>`; a trailing `/views/<n>` is fine. `false` = board sync off (silences `github-project-board-sync-unconfigured`). | absent → board sync skipped |
159
+ | `progress` | Status option **name** set when a phase starts | `In progress` |
160
+ | `review` | Status option **name** set on hand-off | `In review` |
161
+
162
+ Defaults match GitHub's Kanban and Team planning board templates. `/orgs/` → MCP `owner_type: "org"`, `/users/` → `"user"`. Requires `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) + `BKIT_GH_TOKEN` that reaches the board: fine-grained PAT with org Projects R/W for an org board; classic PAT with `project` for a personal board or a token spanning owners. `update_project_item` finds the item by `item_owner` / `item_repo` / `issue_number` and sets Status by option name. Best-effort, never gates; failure → retry once after 5s, then continue. `Done` is **never written** — ship terminal sets `review`, and a human moves the item to Done on acceptance (§ `issue-update-merged` in `.bkit/workflows.md`).
137
163
 
138
164
  ## linear — notes
139
165
 
140
- Linear `ISSUE_ID`s carry team prefix (e.g. `TEAM-123`) — FID inherits (`team-123-slug`). GitHub FIDs numeric-only (`123-slug`). Cross-provider scripts must tolerate both shapes. `LINEAR_TEAM` = `bkit.linearTeam` from manifest. No separate project board — issue state (`In Progress` / `In Review` / `Done`) carries status → `issue-update-status` no-op.
166
+ Linear `ISSUE_ID`s carry team prefix (e.g. `TEAM-123`) — FID inherits (`team-123-slug`). GitHub FIDs numeric-only (`123-slug`). Cross-provider scripts must tolerate both shapes. `bkit repo info` prints `trackerTeam` / `trackerProject` from `package.json` `bkit.linear.team` / `bkit.linear.project` (null → related search unscoped). No separate project board — issue state carries status → `issue-update-status` no-op.
167
+
168
+ Linear `save_issue` is all-or-nothing: one state or label name the team lacks rejects the whole call, valid fields included, and Linear never creates the missing name. A default team has states Backlog / Todo / In Progress / Done / Canceled / Duplicate and labels Improvement / Feature / Bug. Workflows therefore write labels and state in separate calls, labels first. Each label the transition adds (`add` from `bkit issues labels` / `bkit workflows fail`) is created first with `save_issue_label({ name })`, a workspace label; `already exists` = done. Phase start sets state `bkit.linear.progress` (default `started`, a state type every team has). Hand-off, Failure Path and ship terminal set state `bkit.linear.review` (default `In Review`); on a team without it the state call fails alone, is logged `Unapplied`, and the issue keeps its started state while `bkit:merged` / `bkit:failed` carry the hand-off. Label names resolve case-insensitively.
169
+
170
+ ## jira — setup and notes
171
+
172
+ Jira Cloud only. `ISSUE_ID` = issue key (`PROJ-123`) → FID `proj-123-slug`. MCP server `jira` = Atlassian Rovo MCP `https://mcp.atlassian.com/v2/mcp`, header `Authorization: Bearer ${BKIT_JIRA_API_TOKEN}`. Workflows run locally; no Jira-side trigger starts cloud runs.
173
+
174
+ <!-- prettier-ignore -->
175
+ | `package.json` `bkit.jira` key | Value |
176
+ | --- | --- |
177
+ | `site` | `https://<site>.atlassian.net` — every call's `cloudId`; bare `<site>` rejected |
178
+ | `project` | project key (`PROJ`); scopes related search + `bkit-utility-update-tracker`; absent → unscoped |
179
+ | `progress` | status phase start moves to; default `In Progress` |
180
+ | `review` | status hand-off, Failure Path and ship terminal move to; default `In Review` |
181
+
182
+ **Setup** (once):
183
+
184
+ 1. Org admin: https://admin.atlassian.com → org owning `<site>.atlassian.net` → **Rovo** → **Rovo MCP server** (or admin search `mcp`) → **Authentication** → **Allow API token authentication** on; **Permissions**: **Read**, **Write**, **Search** allowed (no **Delete** / **Manage** needed). **Connectors** is the wrong page; **Domains** applies to OAuth only.
185
+ 2. Each person: https://id.atlassian.com/manage-profile/security/api-tokens → **Create API token with scopes** (not classic) → app **Atlassian MCP V2** (not **Jira**, not **Atlassian MCP**) → Jira read / write / search scopes (`read:jira:agent-interface`, `write:jira:agent-interface`, `search:jira:agent-interface`) → copy token (shown once) → `BKIT_JIRA_API_TOKEN` in `.bkit/.env` → `direnv allow`. Token works on MCP only; Jira REST API answers 401.
186
+ 3. `bkit install --tracker=jira`; set `bkit.jira.site` + `bkit.jira.project`. Claude Code: approve project `.mcp.json` once in an interactive `claude` session (`claude mcp list` shows "Pending approval" until then).
187
+
188
+ **Behaviour workflows rely on:**
189
+
190
+ - Status changes only by transition: workflows list the issue's transitions (`executeRead` `listJiraIssueTransitions`) and fire the one whose `to.name` = target status; none → `Unapplied`, labels still land. Basic team-managed boards may lack `In Review` → set `bkit.jira.review` to a status the board has.
191
+ - Labels: `getJiraIssue` returns them only with `view: "evidence"` (or `"full"`); `editJiraIssue` replaces the whole set; Jira creates a label on first use; storage case-sensitive, JQL search not.
192
+ - Comments: posted as markdown, stored as Atlassian Document Format, read back as markdown with same meaning, not same bytes (`-` bullets → `*`, `*em*` → `_em_`, extra blank lines; checkboxes and `> [!NOTE]` alerts come back escaped). One comment Jira cannot express in markdown (mention, image, panel) turns its whole page HTML (`appliedContentFormat: "html"`) → workflows re-read that page one comment per call. Max 32,767 characters → workflows split at line breaks.
193
+ - Blockers: native `Blocks` link; `createJiraIssueLink` reads backwards — `inwardIssue` = blocker, `outwardIssue` = blocked.
194
+ - No type labels: the issue type (Bug / Task / Story) carries type.
195
+
196
+ <!-- prettier-ignore -->
197
+ | Symptom | Fix |
198
+ | --- | --- |
199
+ | Only 4 tools listed (`getTeamworkGraphContext` …), no Jira tools | URL `/v2/mcp`, not `/v1/mcp` |
200
+ | Every call: `Cloud id: … isn't explicitly granted by the user` | Scoped **Atlassian MCP V2** token sent as `Bearer`, not classic token or `Basic` |
201
+ | `missing the scope claim` | Classic token → create token with scopes |
202
+ | `Failed to fetch cloud ID for: <site>` | `bkit.jira.site` = full `https://<site>.atlassian.net` |
203
+ | `Request must be an initialize request if no session ID is provided` (scripted call) | `initialize` first, then send `Mcp-Session-Id` |
204
+ | HTTP 403 Cloudflare 1010 (scripted call) | Send a non-default `User-Agent` |