@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.
- package/.bkit/README.md +19 -7
- package/.bkit/core/.agents/rules.md +24 -9
- package/.bkit/core/.bkit/README.md +18 -6
- package/.bkit/core/.bkit/cloud.md +46 -15
- package/.bkit/core/.bkit/comparison.md +2 -2
- package/.bkit/core/.bkit/install.md +19 -18
- package/.bkit/core/.bkit/pipeline.md +3 -1
- package/.bkit/core/.bkit/prompts.md +38 -20
- package/.bkit/core/.bkit/providers.md +6 -6
- package/.bkit/core/.bkit/templates.md +44 -13
- package/.bkit/core/.bkit/trackers.md +99 -35
- package/.bkit/core/.bkit/workflows.md +50 -45
- package/.bkit/core/AGENTS.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-issues.md +22 -6
- package/.bkit/core/engine/checks/after/auth.ts +88 -45
- package/.bkit/core/engine/checks/after/ci-yml.ts +0 -1
- package/.bkit/core/engine/checks/after/github.ts +42 -78
- package/.bkit/core/engine/checks/after/index.ts +1 -6
- package/.bkit/core/engine/checks/after/tools.ts +1 -1
- package/.bkit/core/engine/checks/before/env.ts +28 -18
- package/.bkit/core/engine/checks/before/mcp.ts +4 -2
- package/.bkit/core/engine/checks/tips/catalogue.ts +15 -2
- package/.bkit/core/engine/checks/tips/index.ts +5 -2
- package/.bkit/core/engine/cli.ts +7 -5
- package/.bkit/core/engine/commands/ci/ci.ts +107 -0
- package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
- package/.bkit/core/engine/commands/workflow/issues.ts +61 -63
- package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
- package/.bkit/core/engine/commands/workflow/prs.ts +3 -1
- package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +5 -1
- package/.bkit/core/engine/commands/workflow/steps.ts +2 -2
- package/.bkit/core/engine/commands/workflow/workflows.ts +9 -4
- package/.bkit/core/engine/commands/workflow/worktrees.ts +91 -14
- package/.bkit/core/engine/install/manifest.ts +31 -10
- package/.bkit/core/engine/install/modules/cloud.ts +3 -1
- package/.bkit/core/engine/install/modules/core.ts +153 -4
- package/.bkit/core/engine/install/modules/opencode.ts +5 -0
- package/.bkit/core/engine/install/write.ts +37 -1
- package/.bkit/core/engine/render/trackers.ts +35 -23
- package/.bkit/core/engine/shared/egress.ts +6 -0
- package/.bkit/core/engine/shared/settings.ts +130 -11
- package/.bkit/core/hooks/guardrails-tiers.js +1 -1
- package/.bkit/core/prompts/bkit-audit-generate.md +42 -12
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -0
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
- package/.bkit/core/prompts/bkit-design-generate.md +4 -1
- package/.bkit/core/prompts/bkit-plan-generate.md +5 -3
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
- package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
- package/.bkit/core/prompts/bkit-utility-update-failures.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
- package/.bkit/core/workflows/bkit-auto.md +19 -6
- package/.bkit/core/workflows/bkit-build.md +59 -17
- package/.bkit/core/workflows/bkit-debug.md +64 -20
- package/.bkit/core/workflows/bkit-design.md +83 -28
- package/.bkit/core/workflows/bkit-plan.md +61 -20
- package/.bkit/core/workflows/bkit-ship.md +48 -18
- package/.bkit/shared/.bkit/.env.example +8 -0
- package/.bkit/shared/.claude/settings.json +3 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
- package/.bkit/shared/.cursor/mcp.json +11 -4
- package/.bkit/shared/.mcp.json +11 -4
- package/.bkit/shared/.opencode/opencode.json +2 -0
- package/.bkit/shared/docs/deployments.md +6 -7
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/testing.md +13 -5
- package/.bkit/templates/.github/renovate.json5 +1 -1
- package/.bkit/templates/.github/workflows/bkit-ci.yml +21 -115
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
- package/.bkit/templates/.husky/pre-commit +4 -4
- package/.bkit/templates/.husky/pre-push +107 -18
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
- package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
- package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
- package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
- package/CHANGELOG.md +67 -1
- package/README.md +16 -6
- package/dist/checks/after/auth.js +81 -45
- package/dist/checks/after/ci-yml.js +0 -1
- package/dist/checks/after/github.js +41 -76
- package/dist/checks/after/index.js +2 -7
- package/dist/checks/after/tools.js +1 -1
- package/dist/checks/before/env.js +24 -17
- package/dist/checks/before/mcp.js +4 -2
- package/dist/checks/tips/catalogue.js +14 -2
- package/dist/checks/tips/index.js +4 -2
- package/dist/cli.js +7 -5
- package/dist/commands/ci/ci.js +100 -0
- package/dist/commands/install/uninstall.js +42 -0
- package/dist/commands/workflow/fids.js +22 -15
- package/dist/commands/workflow/issues.js +53 -61
- package/dist/commands/workflow/ledgers.js +26 -11
- package/dist/commands/workflow/prs.js +3 -1
- package/dist/commands/workflow/repo.js +6 -0
- package/dist/commands/workflow/roadmap.js +3 -1
- package/dist/commands/workflow/steps.js +2 -2
- package/dist/commands/workflow/workflows.js +9 -4
- package/dist/commands/workflow/worktrees.js +74 -13
- package/dist/install/manifest.js +30 -10
- package/dist/install/modules/cloud.js +3 -1
- package/dist/install/modules/core.js +157 -5
- package/dist/install/modules/opencode.js +6 -0
- package/dist/install/write.js +26 -2
- package/dist/render/trackers.js +34 -20
- package/dist/shared/egress.js +6 -0
- package/dist/shared/settings.js +59 -7
- 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` / `
|
|
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
|
-
> -
|
|
15
|
-
> - New tracker
|
|
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
|
|
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
|
|
23
|
+
### Per-tracker group (`github` / `linear` / `jira`)
|
|
24
24
|
|
|
25
|
-
Every call site = consecutive `github` → `linear`
|
|
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:
|
|
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 `
|
|
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
|
|
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
|
|
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 (
|
|
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
|
|
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`
|
|
76
|
-
| `issue-update-review` | phase Close hand-off (non-terminal) | no-op (label carries) | `save_issue`
|
|
77
|
-
| `issue-update-failed` | Failure Path additive `bkit:failed` | `issue_write` labels | `save_issue`
|
|
78
|
-
| `issue-update-merged` | Ship terminal — `bkit:merged` + In Review (issue left open; human closes) | `issue_write` `bkit:merged` (no close) | `save_issue`
|
|
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 `
|
|
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
|
|
131
|
-
|
|
|
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.
|
|
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. `
|
|
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` |
|