@cbartens/bkit 5.2.3 → 5.3.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 (254) hide show
  1. package/.bkit/README.md +29 -12
  2. package/.bkit/core/.agents/context.md +1 -1
  3. package/.bkit/core/.agents/docs.md +1 -1
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +1 -1
  5. package/.bkit/core/.agents/rules.md +11 -0
  6. package/.bkit/core/.bkit/README.md +28 -11
  7. package/.bkit/core/.bkit/cloud.md +9 -8
  8. package/.bkit/core/.bkit/comparison.md +68 -345
  9. package/.bkit/core/.bkit/install.md +15 -9
  10. package/.bkit/core/.bkit/lite.md +73 -0
  11. package/.bkit/core/.bkit/pipeline.md +345 -0
  12. package/.bkit/core/.bkit/prompts.md +88 -73
  13. package/.bkit/core/.bkit/providers.md +41 -22
  14. package/.bkit/core/.bkit/templates.md +125 -18
  15. package/.bkit/core/.bkit/trackers.md +47 -1
  16. package/.bkit/core/.bkit/workflows.md +51 -45
  17. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +1 -1
  18. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +7 -4
  19. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -5
  20. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +9 -1
  21. package/.bkit/core/docs/templates/bkit-audit-adoption.md +10 -2
  22. package/.bkit/core/docs/templates/bkit-audit-agents.md +9 -1
  23. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +9 -1
  24. package/.bkit/core/docs/templates/bkit-audit-analytics.md +9 -1
  25. package/.bkit/core/docs/templates/bkit-audit-annotations.md +10 -2
  26. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +9 -1
  27. package/.bkit/core/docs/templates/bkit-audit-app-store.md +9 -1
  28. package/.bkit/core/docs/templates/bkit-audit-architecture.md +9 -1
  29. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +9 -1
  30. package/.bkit/core/docs/templates/bkit-audit-config.md +9 -1
  31. package/.bkit/core/docs/templates/bkit-audit-cost.md +10 -2
  32. package/.bkit/core/docs/templates/bkit-audit-coverage.md +9 -1
  33. package/.bkit/core/docs/templates/bkit-audit-database.md +9 -1
  34. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +9 -1
  35. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +9 -1
  36. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +22 -10
  37. package/.bkit/core/docs/templates/bkit-audit-documentation.md +9 -1
  38. package/.bkit/core/docs/templates/bkit-audit-duplication.md +9 -1
  39. package/.bkit/core/docs/templates/bkit-audit-failures.md +9 -1
  40. package/.bkit/core/docs/templates/bkit-audit-flakes.md +10 -2
  41. package/.bkit/core/docs/templates/bkit-audit-gates.md +9 -1
  42. package/.bkit/core/docs/templates/bkit-audit-issues.md +9 -1
  43. package/.bkit/core/docs/templates/bkit-audit-llm.md +29 -15
  44. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -2
  45. package/.bkit/core/docs/templates/bkit-audit-models.md +9 -1
  46. package/.bkit/core/docs/templates/bkit-audit-privacy.md +9 -1
  47. package/.bkit/core/docs/templates/bkit-audit-prompts.md +11 -3
  48. package/.bkit/core/docs/templates/bkit-audit-red-team.md +19 -9
  49. package/.bkit/core/docs/templates/bkit-audit-reliability.md +9 -1
  50. package/.bkit/core/docs/templates/bkit-audit-repo.md +10 -2
  51. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -5
  52. package/.bkit/core/docs/templates/bkit-audit-slop.md +9 -1
  53. package/.bkit/core/docs/templates/bkit-audit-testing.md +14 -5
  54. package/.bkit/core/docs/templates/bkit-audit-usability.md +9 -1
  55. package/.bkit/core/docs/templates/bkit-plan.md +8 -6
  56. package/.bkit/core/engine/checks/after/auth.ts +9 -9
  57. package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
  58. package/.bkit/core/engine/checks/after/github.ts +29 -120
  59. package/.bkit/core/engine/checks/after/index.ts +2 -2
  60. package/.bkit/core/engine/checks/after/managed.ts +8 -28
  61. package/.bkit/core/engine/checks/after/tools.ts +3 -15
  62. package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
  63. package/.bkit/core/engine/checks/before/index.ts +7 -43
  64. package/.bkit/core/engine/checks/before/mcp.ts +17 -8
  65. package/.bkit/core/engine/checks/before/repo.ts +9 -12
  66. package/.bkit/core/engine/checks/status-holes.ts +4 -5
  67. package/.bkit/core/engine/checks/tips/catalogue.ts +70 -24
  68. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  69. package/.bkit/core/engine/checks/tips/index.ts +37 -8
  70. package/.bkit/core/engine/cli.ts +39 -16
  71. package/.bkit/core/engine/commands/analysis.ts +36 -26
  72. package/.bkit/core/engine/commands/comply.ts +17 -16
  73. package/.bkit/core/engine/commands/harvest.ts +12 -12
  74. package/.bkit/core/engine/commands/install/doctor.ts +57 -28
  75. package/.bkit/core/engine/commands/install/install.ts +62 -126
  76. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  77. package/.bkit/core/engine/commands/install/upgrade.ts +58 -53
  78. package/.bkit/core/engine/commands/lib.ts +35 -10
  79. package/.bkit/core/engine/commands/tips.ts +8 -5
  80. package/.bkit/core/engine/commands/workflow/branches.ts +65 -11
  81. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  82. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  83. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  84. package/.bkit/core/engine/commands/workflow/prs.ts +4 -2
  85. package/.bkit/core/engine/commands/workflow/repo.ts +18 -4
  86. package/.bkit/core/engine/commands/workflow/roadmap.ts +4 -3
  87. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  88. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  89. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  90. package/.bkit/core/engine/commands/workflow/workflows.ts +19 -17
  91. package/.bkit/core/engine/commands/workflow/workstreams.ts +2 -1
  92. package/.bkit/core/engine/commands/workflow/worktrees.ts +13 -5
  93. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  94. package/.bkit/core/engine/install/manifest.ts +14 -7
  95. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  96. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  97. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  98. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  99. package/.bkit/core/engine/install/modules/core.ts +91 -70
  100. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  101. package/.bkit/core/engine/install/modules/index.ts +7 -1
  102. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  103. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  104. package/.bkit/core/engine/install/placeholders.ts +3 -18
  105. package/.bkit/core/engine/install/write.ts +59 -12
  106. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  107. package/.bkit/core/engine/render/hosts.ts +47 -67
  108. package/.bkit/core/engine/render/models.ts +29 -11
  109. package/.bkit/core/engine/shared/bkit-latest.ts +164 -0
  110. package/.bkit/core/engine/shared/branches.ts +13 -0
  111. package/.bkit/core/engine/shared/egress.ts +3 -3
  112. package/.bkit/core/engine/shared/json.ts +18 -1
  113. package/.bkit/core/engine/shared/package-json.ts +63 -0
  114. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  115. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  116. package/.bkit/core/engine/shared/settings.ts +36 -0
  117. package/.bkit/core/engine/shared/timeouts.ts +6 -0
  118. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  119. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  120. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  121. package/.bkit/core/prompts/bkit-audit-generate.md +65 -10
  122. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  123. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  124. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  125. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  126. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  127. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  128. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  129. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  130. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  131. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  132. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  133. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  134. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  135. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  136. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  137. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  138. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  139. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  140. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  141. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  142. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  143. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  144. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  145. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  146. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  147. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  148. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  149. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  150. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  151. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  152. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  153. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  154. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  155. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  156. package/.bkit/core/workflows/bkit-build.md +4 -4
  157. package/.bkit/core/workflows/bkit-debug.md +70 -34
  158. package/.bkit/core/workflows/bkit-design.md +3 -3
  159. package/.bkit/core/workflows/bkit-plan.md +12 -5
  160. package/.bkit/core/workflows/bkit-ship.md +6 -6
  161. package/.bkit/shared/.claude/bkit-cloud.md +46 -13
  162. package/.bkit/shared/.claude/settings.json +18 -0
  163. package/.bkit/shared/.cursor/mcp.json +2 -1
  164. package/.bkit/shared/.opencode/opencode.json +19 -1
  165. package/.bkit/shared/docs/deployments.md +20 -4
  166. package/.bkit/shared/docs/security.md +8 -6
  167. package/.bkit/shared/docs/testing.md +9 -5
  168. package/.bkit/templates/.cursor/Dockerfile +30 -16
  169. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  170. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  171. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  172. package/.bkit/templates/.github/renovate.json5 +91 -12
  173. package/.bkit/templates/.github/workflows/bkit-ci.yml +66 -53
  174. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  175. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  176. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  177. package/.bkit/templates/.husky/pre-push +15 -3
  178. package/.bkit/templates/.oxlintrc.json +21 -0
  179. package/.bkit/templates/docs/capabilities.md +1 -1
  180. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  181. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  182. package/.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs +115 -0
  183. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  184. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  185. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  186. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  187. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  188. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  189. package/CHANGELOG.md +67 -3
  190. package/README.md +258 -129
  191. package/dist/checks/after/auth.js +10 -11
  192. package/dist/checks/after/ci-yml.js +11 -14
  193. package/dist/checks/after/github.js +32 -125
  194. package/dist/checks/after/index.js +3 -2
  195. package/dist/checks/after/managed.js +8 -24
  196. package/dist/checks/after/tools.js +3 -16
  197. package/dist/checks/before/context-fetch.js +1 -21
  198. package/dist/checks/before/index.js +6 -42
  199. package/dist/checks/before/mcp.js +14 -9
  200. package/dist/checks/before/repo.js +8 -11
  201. package/dist/checks/status-holes.js +5 -6
  202. package/dist/checks/tips/catalogue.js +60 -18
  203. package/dist/checks/tips/detect.js +41 -2
  204. package/dist/checks/tips/index.js +25 -5
  205. package/dist/cli.js +34 -14
  206. package/dist/commands/analysis.js +21 -5
  207. package/dist/commands/comply.js +20 -18
  208. package/dist/commands/harvest.js +12 -13
  209. package/dist/commands/install/doctor.js +55 -23
  210. package/dist/commands/install/install.js +62 -118
  211. package/dist/commands/install/uninstall.js +165 -31
  212. package/dist/commands/install/upgrade.js +55 -49
  213. package/dist/commands/lib.js +32 -10
  214. package/dist/commands/tips.js +6 -3
  215. package/dist/commands/workflow/branches.js +57 -13
  216. package/dist/commands/workflow/counters.js +17 -7
  217. package/dist/commands/workflow/fids.js +39 -0
  218. package/dist/commands/workflow/ledgers.js +3 -1
  219. package/dist/commands/workflow/prs.js +3 -3
  220. package/dist/commands/workflow/repo.js +16 -4
  221. package/dist/commands/workflow/roadmap.js +4 -4
  222. package/dist/commands/workflow/runs.js +5 -5
  223. package/dist/commands/workflow/steps.js +1 -0
  224. package/dist/commands/workflow/tests.js +16 -3
  225. package/dist/commands/workflow/workflows.js +19 -18
  226. package/dist/commands/workflow/workstreams.js +2 -1
  227. package/dist/commands/workflow/worktrees.js +4 -5
  228. package/dist/install/cloud-env.js +10 -23
  229. package/dist/install/manifest.js +14 -7
  230. package/dist/install/modules/antigravity.js +15 -26
  231. package/dist/install/modules/claude.js +17 -21
  232. package/dist/install/modules/cloud.js +6 -2
  233. package/dist/install/modules/codex.js +15 -29
  234. package/dist/install/modules/core.js +82 -63
  235. package/dist/install/modules/cursor.js +6 -9
  236. package/dist/install/modules/index.js +6 -1
  237. package/dist/install/modules/opencode.js +41 -72
  238. package/dist/install/network-allowlist.js +62 -0
  239. package/dist/install/placeholders.js +3 -16
  240. package/dist/install/write.js +55 -15
  241. package/dist/ledgers/telemetry.js +5 -4
  242. package/dist/render/hosts.js +30 -55
  243. package/dist/render/models.js +20 -9
  244. package/dist/shared/bkit-latest.js +150 -0
  245. package/dist/shared/branches.js +11 -0
  246. package/dist/shared/egress.js +0 -2
  247. package/dist/shared/json.js +14 -0
  248. package/dist/shared/package-json.js +61 -0
  249. package/dist/shared/package-roots.js +0 -8
  250. package/dist/shared/protected-paths.js +5 -122
  251. package/dist/shared/settings.js +18 -1
  252. package/dist/shared/timeouts.js +6 -0
  253. package/package.json +21 -17
  254. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -42,6 +42,7 @@ import { TIMEOUTS } from "../../shared/timeouts.js";
42
42
  import { gradeCompliance } from "../comply.js";
43
43
  import {
44
44
  CommandError,
45
+ DEV,
45
46
  EXIT,
46
47
  git,
47
48
  parseJson,
@@ -55,7 +56,7 @@ import {
55
56
  type FlagValue,
56
57
  type RunContext,
57
58
  } from "../lib.js";
58
- import { pushBranch, readAnchor, stampAnchor } from "./branches.js";
59
+ import { anchorBkitStatus, pushBranch, readAnchor, stampAnchor } from "./branches.js";
59
60
  import {
60
61
  AUTO_LABEL,
61
62
  AUTO_ROUTE_SUFFIX,
@@ -354,15 +355,15 @@ async function shipFlush(
354
355
  return { code: EXIT.OK, pushed: false, ref: null, skipped: "dev-lock-busy" };
355
356
  }
356
357
  release = () => releaseLock(lock.path, { workflow: "ship", fid: o.fid, token: lock.token });
357
- runGit(root, ["checkout", "dev"]);
358
- if (git(root, ["branch", "--show-current"]) !== "dev") {
358
+ runGit(root, ["checkout", DEV]);
359
+ if (git(root, ["branch", "--show-current"]) !== DEV) {
359
360
  release();
360
361
  ctx.log(`not on dev after checkout — FAILED bookkeeping left uncommitted in ${bookRoot}`);
361
362
  return { code: EXIT_FLUSH_FAILED, pushed: false, ref: null, skipped: null };
362
363
  }
363
- runGit(root, ["pull", "--ff-only", "origin", "dev"]);
364
+ runGit(root, ["pull", "--ff-only", "origin", DEV]);
364
365
  wt = root;
365
- target = "dev";
366
+ target = DEV;
366
367
  } else {
367
368
  ctx.log("RUNTIME_DEVPUSHES=false — the FAILED record commits on the current branch");
368
369
  target = git(wt, ["branch", "--show-current"]) ?? "";
@@ -789,7 +790,7 @@ export function closeWorkflow(
789
790
  const ref =
790
791
  o.ref ??
791
792
  (["design", "plan", "ship"].includes(workflow)
792
- ? "dev"
793
+ ? DEV
793
794
  : (git(cwd, ["branch", "--show-current"]) ?? "HEAD"));
794
795
  const artifacts = artifactLinks(
795
796
  where.root,
@@ -884,8 +885,8 @@ async function shipClose(ctx: RunContext, o: CloseInput, token: string | undefin
884
885
  try {
885
886
  let wt: string;
886
887
  if (o.devPushes) {
887
- runGit(root, ["checkout", "dev"]);
888
- if (git(root, ["branch", "--show-current"]) !== "dev")
888
+ runGit(root, ["checkout", DEV]);
889
+ if (git(root, ["branch", "--show-current"]) !== DEV)
889
890
  return fail("not on dev after checkout — aborting dev ops");
890
891
  wt = root;
891
892
  } else {
@@ -898,7 +899,7 @@ async function shipClose(ctx: RunContext, o: CloseInput, token: string | undefin
898
899
  if (o.devPushes) {
899
900
  closeRoot = wt;
900
901
  } else {
901
- if (!runGit(wt, ["fetch", "origin", "dev"]).ok)
902
+ if (!runGit(wt, ["fetch", "origin", DEV]).ok)
902
903
  return fail(`fetch origin dev failed — close bookkeeping left uncommitted in ${wt}`);
903
904
  closeRoot = path.join(outbox, "close");
904
905
  if (fs.existsSync(closeRoot)) runGit(wt, ["worktree", "remove", "--force", closeRoot]);
@@ -924,11 +925,11 @@ async function shipClose(ctx: RunContext, o: CloseInput, token: string | undefin
924
925
  );
925
926
  if (released.removeFailed) return fail("Lock removal failed");
926
927
  if (o.devPushes) {
927
- if (!runGit(closeRoot, ["push", "origin", "dev"]).ok) {
928
+ if (!runGit(closeRoot, ["push", "origin", DEV]).ok) {
928
929
  ctx.log("dev push failed");
929
930
  return { code: EXIT_PUSH_FAILED, out };
930
931
  }
931
- landed = { ref: "dev", via: "dev-push" };
932
+ landed = { ref: DEV, via: "dev-push" };
932
933
  }
933
934
  } finally {
934
935
  releaseLock(lock.path, { workflow: "ship", fid: o.fid, token: lock.token });
@@ -936,7 +937,7 @@ async function shipClose(ctx: RunContext, o: CloseInput, token: string | undefin
936
937
 
937
938
  if (!o.devPushes) {
938
939
  if (runGit(closeRoot, ["push", "origin", "HEAD:dev"]).ok) {
939
- landed = { ref: "dev", via: "head-push" };
940
+ landed = { ref: DEV, via: "head-push" };
940
941
  } else {
941
942
  // dev refused the push: publish the close commit through its own PR.
942
943
  const branch = `ship-close/${o.fid}`;
@@ -947,7 +948,7 @@ async function shipClose(ctx: RunContext, o: CloseInput, token: string | undefin
947
948
  "pr",
948
949
  "create",
949
950
  "--base",
950
- "dev",
951
+ DEV,
951
952
  "--head",
952
953
  branch,
953
954
  "--title",
@@ -956,7 +957,7 @@ async function shipClose(ctx: RunContext, o: CloseInput, token: string | undefin
956
957
  "",
957
958
  ]);
958
959
  if (!created.ok) return fail(`gh pr create failed: ${created.stderr}`);
959
- const pr = probePr(closeRoot, { head: branch, base: "dev", state: "open" });
960
+ const pr = probePr(closeRoot, { head: branch, base: DEV, state: "open" });
960
961
  const number = pr.kind === "ok" ? pr.pr?.number : undefined;
961
962
  if (number === undefined) return fail(`close PR not found for ${branch}`);
962
963
  const merged = mergePr(
@@ -998,7 +999,7 @@ export function highestVersion(dir: string, workflow: string): { file: string; n
998
999
  return best;
999
1000
  }
1000
1001
 
1001
- /** Stamp `file`'s anchor when a base commit is known (plan: with its design's own anchor). */
1002
+ /** Stamp `file`'s anchor when a base commit is known (plan: with its design's own anchor; both: the bkit release). */
1002
1003
  function stamp(cwd: string, file: string, baseSha: string, design?: string): void {
1003
1004
  if (baseSha === "") return;
1004
1005
  const abs = path.resolve(cwd, file);
@@ -1008,7 +1009,8 @@ function stamp(cwd: string, file: string, baseSha: string, design?: string): voi
1008
1009
  ? { path: design, baseSha: readAnchor(fs.readFileSync(designAbs, "utf-8")).baseSha ?? "" }
1009
1010
  : undefined;
1010
1011
  const tmp = `${abs}.bkit-anchor.tmp`;
1011
- fs.writeFileSync(tmp, stampAnchor(fs.readFileSync(abs, "utf-8"), baseSha, d));
1012
+ const text = fs.readFileSync(abs, "utf-8");
1013
+ fs.writeFileSync(tmp, stampAnchor(text, baseSha, d, undefined, anchorBkitStatus(cwd)));
1012
1014
  fs.renameSync(tmp, abs);
1013
1015
  }
1014
1016
 
@@ -1544,7 +1546,7 @@ export const workflowsCommand: CommandSpec = {
1544
1546
  const month = resolveMonth(root, fid, str(ctx.flags.month));
1545
1547
  const artifacts = artifactLinks(
1546
1548
  root,
1547
- str(ctx.flags.ref) ?? "dev",
1549
+ str(ctx.flags.ref) ?? DEV,
1548
1550
  month,
1549
1551
  fid,
1550
1552
  workflow,
@@ -84,7 +84,7 @@ export function parseWorkstreams(md: string): Workstream[] {
84
84
  /** `[]` or `[WS-1, WS-2]`. */
85
85
  export const requiresList = (w: Workstream) => `[${w.requires.join(", ")}]`;
86
86
 
87
- /** The Step 11 comment: one line per workstream, then the design doc link. */
87
+ /** The Step 11 comment: one line per workstream, the issue-body line, then the design doc link. */
88
88
  export function commentBody(
89
89
  ws: Workstream[],
90
90
  opts: { ownerRepo: string; month: string; fid: string },
@@ -95,6 +95,7 @@ export function commentBody(
95
95
  "### Step 11 — Suggested Workstreams",
96
96
  "Advisory only. NEVER auto-trigger.",
97
97
  ...ws.map((w) => `- ${w.id}: ${w.name}. Requires: ${requiresList(w)}`),
98
+ `Filing one issue per workstream: put \`**Parent design:** [${opts.fid}-design.md](${doc})\` in its body, and list the issues it requires in a blocked-by block (.bkit/trackers.md § Issue shapes).`,
98
99
  `[${doc}](https://github.com/${opts.ownerRepo}/blob/dev/${doc})`,
99
100
  ].join("\n");
100
101
  }
@@ -17,12 +17,20 @@ import * as path from "node:path";
17
17
  import { gitEnv } from "../../ledgers/telemetry.js";
18
18
  import { readBkitConfig } from "../../shared/settings.js";
19
19
  import { COULD_NOT_RUN_EXIT_CODES, installCommand } from "../../shared/package-manager.js";
20
- import { CommandError, EXIT, git, repoRoot, runGit, type CommandSpec } from "../lib.js";
20
+ import {
21
+ CommandError,
22
+ DEV,
23
+ EXIT,
24
+ git,
25
+ isSharedBranch,
26
+ repoRoot,
27
+ runGit,
28
+ type CommandSpec,
29
+ } from "../lib.js";
21
30
  import { detect } from "./runtime.js";
22
31
  import { WORKFLOW_FLAG } from "./status.js";
23
32
 
24
33
  const WORKFLOWS = ["design", "plan", "build", "debug", "ship"];
25
- const DEV = "dev";
26
34
  const ORIGIN_DEV = `origin/${DEV}`;
27
35
 
28
36
  export const EXIT_REBASE_CONFLICT = 3;
@@ -103,7 +111,7 @@ function shipBranch(root: string, fid: string, named: string | undefined, sessio
103
111
  if (named) return named;
104
112
  const feat = `feat/${fid}`;
105
113
  if (hasLocal(root, feat) || remoteHas(root, feat) === "yes") return feat;
106
- return session === DEV || session === "main" || session === "" ? feat : session;
114
+ return isSharedBranch(session) || session === "" ? feat : session;
107
115
  }
108
116
 
109
117
  /**
@@ -249,7 +257,7 @@ export function removeWorktree(
249
257
  branch: string | undefined,
250
258
  log: (m: string) => void,
251
259
  ): RemoveResult {
252
- if (branch !== undefined && (branch === DEV || branch === "main")) {
260
+ if (branch !== undefined && isSharedBranch(branch)) {
253
261
  throw new CommandError(EXIT.USAGE, `refusing to delete branch ${branch}`);
254
262
  }
255
263
  const root = repoRoot(cwd);
@@ -368,7 +376,7 @@ export const worktreesCommand: CommandSpec = {
368
376
  );
369
377
  }
370
378
  const target = workflow === "ship" ? shipBranch(root, fid, named, session) : `feat/${fid}`;
371
- if (target === DEV || target === "main") {
379
+ if (isSharedBranch(target)) {
372
380
  throw new CommandError(EXIT_REFUSED, `refusing to ship ${target} as a feature branch`);
373
381
  }
374
382
 
@@ -14,6 +14,7 @@
14
14
  import * as fs from "node:fs";
15
15
  import * as path from "node:path";
16
16
  import type { IssueTracker } from "./manifest.js";
17
+ import { readJsonFile } from "../shared/json.js";
17
18
  import { getSharedRoot } from "../shared/package-roots.js";
18
19
  import { applyTokens, type TokenMap } from "./placeholders.js";
19
20
  import { BKIT_EGRESS_SOURCES, type EgressSource } from "../shared/egress.js";
@@ -246,7 +247,8 @@ export function renderCloudEnvNotes(res: CloudEnvResolution): string {
246
247
  if (!res.hasEnvrc) {
247
248
  return (
248
249
  "_No `.envrc` found — the block above lists only the bkit baseline token names as " +
249
- "placeholders. Add your `.envrc` (`bkit install` seeds one) and re-run to inline real values._"
250
+ "placeholders. Copy `.bkit/templates/.envrc` to the repo root, fill the files it sources, " +
251
+ "and re-run to inline real values._"
250
252
  );
251
253
  }
252
254
  const bullets: string[] = [];
@@ -276,17 +278,12 @@ export function renderCloudEnvNotes(res: CloudEnvResolution): string {
276
278
 
277
279
  /** Parse the pnpm `X.Y.Z` from `package.json` `packageManager` ("" if absent/non-pnpm). */
278
280
  export function resolveConsumerPnpm(cwd: string): string {
279
- try {
280
- const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8")) as Record<
281
- string,
282
- unknown
283
- >;
284
- const pm = typeof pkg["packageManager"] === "string" ? (pkg["packageManager"] as string) : "";
285
- const m = pm.match(/^pnpm@(\d+\.\d+\.\d+)/);
286
- return m?.[1] ?? "";
287
- } catch {
288
- return "";
289
- }
281
+ const read = readJsonFile(path.join(cwd, "package.json"));
282
+ if (!read.ok || typeof read.value !== "object" || read.value === null) return "";
283
+ const pkg = read.value as Record<string, unknown>;
284
+ const pm = typeof pkg["packageManager"] === "string" ? pkg["packageManager"] : "";
285
+ const m = pm.match(/^pnpm@(\d+\.\d+\.\d+)/);
286
+ return m?.[1] ?? "";
290
287
  }
291
288
 
292
289
  /**
@@ -568,31 +565,13 @@ export function resolveClaudeDerivedAllows(cwd: string): string[] {
568
565
  ];
569
566
  }
570
567
 
571
- /** Cursor-relative path of the install-written curl/wget allowlist (guardrails). */
572
- export const NETWORK_ALLOWLIST_RELPATH = path.join(".cursor", "allowlist.json");
573
-
574
- /**
575
- * Write `.cursor/allowlist.json` for Cursor `bkit-guardrails.cjs` (runtime curl/wget host
576
- * checks). Claude/OpenCode bake the same domain set into their own configs at
577
- * install/upgrade — they do not read this file. Call only when the cursor module
578
- * is installed (do not create `.cursor/` for claude-only consumers).
579
- */
580
- export function writeNetworkAllowlistArtifact(
581
- cwd: string,
582
- dryRun: boolean,
583
- ): { path: string; domains: string[]; wrote: boolean } {
584
- const domains = resolveNetworkAllowlist(cwd);
585
- const rel = NETWORK_ALLOWLIST_RELPATH;
586
- return { path: rel, domains, wrote: writeGeneratedJson(cwd, rel, { domains }, dryRun) };
587
- }
588
-
589
568
  /** Cursor-relative path of the install-written Cursor CLI permissions (MCP allows). */
590
569
  export const CURSOR_CLI_PERMISSIONS_RELPATH = path.join(".cursor", "cli.json");
591
570
 
592
571
  /**
593
572
  * Write `.cursor/cli.json` — the project-level Cursor CLI / cloud-agent permissions —
594
573
  * with one `Mcp(<server>:*)` allow per {@link extractMcpServers} entry. bkit-owned and
595
- * regenerated whole, like `.cursor/allowlist.json`: hand edits do not survive, the
574
+ * regenerated whole, like `.bkit/allowlist.json`: hand edits do not survive, the
596
575
  * `mcp-servers` block is the source. Call only when the cursor module is installed.
597
576
  */
598
577
  export function writeCursorCliPermissionsArtifact(
@@ -125,10 +125,17 @@ const CORE_MANIFEST: ManifestEntry[] = [
125
125
  // their own attributes outside the block, so this is markered-text (not whole-file).
126
126
  { path: ".gitattributes", format: "markered-text", module: "core" },
127
127
  { path: ".bkit/version", format: "byte-equal-text", module: "core" },
128
+ // Curl/wget host allowlist read at runtime by every host's bkit-guardrails.cjs (Claude,
129
+ // Cursor, Codex, Antigravity). No template backs it — `writeNetworkAllowlist`
130
+ // (install/network-allowlist.ts) computes the domain set from the consumer's own config,
131
+ // so it is `generated` and its hash is in `canonicalHashes`. Core-owned: it stays until
132
+ // the last host goes (full/core uninstall).
133
+ { path: ".bkit/allowlist.json", format: "byte-equal-text", module: "core", generated: true },
128
134
  // Canonical bkit-authored reference docs. They live package-side under
129
135
  // `.bkit/core/.bkit/` and are read from there at runtime (getBkitDocsRoot); these
130
136
  // consumer copies are force-overwritten mirrors (writeTier1) so a consumer can read
131
- // them in-repo. Whole file is bkit-owned → byte-equal-text (refreshed every install).
137
+ // them in-repo. Whole file is bkit-owned → byte-equal-text (refreshed every install);
138
+ // prompts.md and lite.md are markered-text, keeping the consumer section below `bkit:end`.
132
139
  { path: ".bkit/cloud.md", format: "byte-equal-text", module: "core" },
133
140
  { path: ".bkit/comparison.md", format: "byte-equal-text", module: "core" },
134
141
  { path: ".bkit/install.md", format: "byte-equal-text", module: "core" },
@@ -136,6 +143,8 @@ const CORE_MANIFEST: ManifestEntry[] = [
136
143
  // The MIT notice that travels with the files bkit writes: the full text and copyright
137
144
  // notice. Sourced from `.bkit/core/.bkit/LICENSE.md`.
138
145
  { path: ".bkit/LICENSE.md", format: "byte-equal-text", module: "core" },
146
+ { path: ".bkit/lite.md", format: "markered-text", module: "core" },
147
+ { path: ".bkit/pipeline.md", format: "byte-equal-text", module: "core" },
139
148
  { path: ".bkit/providers.md", format: "byte-equal-text", module: "core" },
140
149
  { path: ".bkit/prompts.md", format: "markered-text", module: "core" },
141
150
  { path: ".bkit/templates.md", format: "byte-equal-text", module: "core" },
@@ -209,7 +218,8 @@ const CLAUDE_MANIFEST: ManifestEntry[] = [
209
218
  // `gate-missing-called-scripts` advisory names any that are missing.
210
219
  //
211
220
  // The SAME names are what the git hook templates run (`.husky/pre-commit`,
212
- // `.husky/pre-push`). `bkit-ci.yml` does NOT call the gates; it calls the scripts directly.
221
+ // `.husky/pre-push`). `bkit-ci.yml` does NOT call the gates; it calls the same scripts
222
+ // directly, one step each.
213
223
  //
214
224
  // `lint:slop` is in no gate: `slop-scan scan` is report-only and never fails. The gate
215
225
  // that fails on new findings is `slop:delta`.
@@ -223,7 +233,8 @@ export const BKIT_GATE_SCRIPTS: Readonly<Record<string, string>> = {
223
233
  // `.husky/pre-commit`: prettier --write over staged files, and nothing else —
224
234
  // seconds, not minutes. Prose is a whole-repo scan, so it gates at pre-push.
225
235
  "bkit:gate:format": "pnpm lint-staged",
226
- // Everything that needs no test runner. Mirrors the bkit-tests-static CI job.
236
+ // Everything that needs no test runner. Every part has a matching step in the
237
+ // bkit-tests-static CI job; audits/templates/template-ci-yml.test.ts fails when one is missing.
227
238
  // Callers: build's plan-execute loop between tasks, and the `.husky/pre-push` revert
228
239
  // path.
229
240
  "bkit:gate:static":
@@ -339,10 +350,6 @@ const CURSOR_MANIFEST: ManifestEntry[] = [
339
350
  format: "markered-text",
340
351
  module: "cursor",
341
352
  },
342
- // Curl/wget host allowlist read at runtime by bkit-guardrails.cjs. No template backs it —
343
- // `writeNetworkAllowlistArtifact` (install/cloud-env.ts) computes the domain set from the
344
- // consumer's own config, so it is `generated` and its hash is in `canonicalHashes`.
345
- { path: ".cursor/allowlist.json", format: "byte-equal-text", module: "cursor", generated: true },
346
353
  // Cursor CLI / cloud-agent MCP allows — `writeCursorCliPermissionsArtifact`
347
354
  // (install/cloud-env.ts) renders it from the consumer's `mcp-servers` block; same contract.
348
355
  { path: ".cursor/cli.json", format: "byte-equal-text", module: "cursor", generated: true },
@@ -19,14 +19,9 @@ import {
19
19
  } from "../../shared/package-roots.js";
20
20
  import { type IssueTracker, DEFAULT_ISSUE_TRACKER } from "../manifest.js";
21
21
  import { substituteWorkflow } from "../../render/trackers.js";
22
+ import { readInstallingVersion } from "../../shared/package-json.js";
22
23
  import type { ModuleContext } from "./index.js";
23
- import {
24
- BKIT_PREFIX,
25
- installFile,
26
- listMdFiles,
27
- readInstallingVersion,
28
- trackMirrorWrite,
29
- } from "./core.js";
24
+ import { BKIT_PREFIX, installFile, listMdFiles, removeOrphans, trackMirrorWrite } from "./core.js";
30
25
 
31
26
  // ---------------------------------------------------------------------------
32
27
  // runAntigravityModule — Google Antigravity IDE host (opt-in via --antigravity)
@@ -115,16 +110,12 @@ export function renderAntigravityAgentsSkills(ctx: ModuleContext): string[] {
115
110
  }
116
111
  }
117
112
 
118
- // Orphan sweep is bkit-prefix scoped — the plugin's agents/ is bkit-owned.
119
- if (fs.existsSync(dest)) {
120
- for (const f of fs.readdirSync(dest)) {
121
- if (!f.startsWith(BKIT_PREFIX)) continue;
122
- if (sourceSet.has(f)) continue;
123
- const rel = path.join(dest, f);
124
- if (!dryRun) fs.rmSync(rel, { force: true });
125
- console.log(`${logPrefix} ${tag}delete orphan: ${rel}`);
126
- trackMirrorWrite(ctx, rel, written);
127
- }
113
+ // Orphan sweep is bkit-prefix scoped — the plugin's agents/ is bkit-owned, so every
114
+ // bkit-* entry counts, whatever its extension.
115
+ for (const f of removeOrphans(dest, sourceSet, dryRun, BKIT_PREFIX, { extension: "" })) {
116
+ const rel = path.join(dest, f);
117
+ console.log(`${logPrefix} ${tag}delete orphan: ${rel}`);
118
+ trackMirrorWrite(ctx, rel, written);
128
119
  }
129
120
  }
130
121
 
@@ -148,15 +139,13 @@ export function renderAntigravityAgentsSkills(ctx: ModuleContext): string[] {
148
139
  }
149
140
 
150
141
  // Prefix-scoped sweep inside the bkit plugin's skills/.
151
- if (fs.existsSync(ANTIGRAVITY_SKILLS_DIR)) {
152
- for (const d of fs.readdirSync(ANTIGRAVITY_SKILLS_DIR)) {
153
- if (!d.startsWith(BKIT_PREFIX)) continue;
154
- if (sourceStems.has(d)) continue;
155
- const rel = path.join(ANTIGRAVITY_SKILLS_DIR, d);
156
- if (!dryRun) fs.rmSync(rel, { recursive: true, force: true });
157
- console.log(`${logPrefix} ${tag}delete orphan: ${rel}`);
158
- trackMirrorWrite(ctx, rel, written);
159
- }
142
+ const orphans = removeOrphans(ANTIGRAVITY_SKILLS_DIR, sourceStems, dryRun, BKIT_PREFIX, {
143
+ wholeFolders: true,
144
+ });
145
+ for (const d of orphans) {
146
+ const rel = path.join(ANTIGRAVITY_SKILLS_DIR, d);
147
+ console.log(`${logPrefix} ${tag}delete orphan: ${rel}`);
148
+ trackMirrorWrite(ctx, rel, written);
160
149
  }
161
150
  }
162
151
 
@@ -8,10 +8,13 @@ import {
8
8
  writeTier2,
9
9
  writeTier2JsonContained,
10
10
  ensureDir,
11
+ mergeTrackerEntry,
12
+ trackerEntryInSync,
11
13
  type WriteSet,
12
14
  type JsonValue,
13
15
  } from "../write.js";
14
16
  import { readBkitVersion, stampManagedVersion } from "../version-file.js";
17
+ import { readJsonFile } from "../../shared/json.js";
15
18
  import { applyEffortRemap } from "../../render/hosts.js";
16
19
  import type { PreflightFinding } from "../../checks/before/index.js";
17
20
  import {
@@ -23,15 +26,9 @@ import {
23
26
  import { type IssueTracker, DEFAULT_ISSUE_TRACKER } from "../manifest.js";
24
27
  import { substituteWorkflow } from "../../render/trackers.js";
25
28
  import { writeClaudeCloudDoc, resolveClaudeDerivedAllows } from "../cloud-env.js";
29
+ import { readInstallingVersion } from "../../shared/package-json.js";
26
30
  import type { ModuleContext } from "./index.js";
27
- import {
28
- BKIT_PREFIX,
29
- installFile,
30
- listMdFiles,
31
- readInstallingVersion,
32
- removeOrphans,
33
- trackMirrorWrite,
34
- } from "./core.js";
31
+ import { BKIT_PREFIX, installFile, listMdFiles, removeOrphans, trackMirrorWrite } from "./core.js";
35
32
 
36
33
  export function renderClaudeAgentsCommands(ctx: ModuleContext): string[] {
37
34
  const { dryRun, logPrefix, effortMap } = ctx;
@@ -247,14 +244,11 @@ export function enrichClaudeSettingsAllows(
247
244
  advisories?: PreflightFinding[],
248
245
  ): readonly string[] | null {
249
246
  if (!fs.existsSync(settingsDst)) return null;
250
- let doc: {
247
+ const settings = readJsonFile(settingsDst);
248
+ if (!settings.ok) return null;
249
+ const doc = settings.value as {
251
250
  permissions?: { allow?: string[] };
252
251
  };
253
- try {
254
- doc = JSON.parse(fs.readFileSync(settingsDst, "utf-8")) as typeof doc;
255
- } catch {
256
- return null;
257
- }
258
252
  const allow = doc.permissions?.allow;
259
253
  if (!Array.isArray(allow)) return null;
260
254
 
@@ -310,12 +304,14 @@ export function buildMcpJson(templatePath: string, tracker: IssueTracker): strin
310
304
 
311
305
  /**
312
306
  * Reconcile bkit's tracker entry into a consumer's `.mcp.json` / `.cursor/mcp.json`. bkit
313
- * owns exactly one key, `mcpServers[<tracker>]`, and sets it to the template's entry; every
307
+ * owns exactly one key, `mcpServers[<tracker>]`, and within it only what the template sets
308
+ * (`mergeTrackerEntry`: extra keys, headers and toolsets stay the consumer's); every
314
309
  * other key and the existing key order stay the consumer's. Absent file → write the
315
310
  * `buildMcpJson` render. Malformed JSON → throw (refuse to merge; the consumer fixes it).
316
311
  * Tracker `none` owns no entry, so a present file is left alone. Writes only on change, so
317
- * dry-run and live compute the identical WriteSet. Another tracker's entry from an earlier
318
- * install is left in place (`detectExtraMcpServers` advises on it).
312
+ * dry-run and live compute the identical WriteSet. Another tracker's entry is not touched
313
+ * here: a `--tracker` switch removes an unedited one first (`removeUnusedTrackerMcpEntries`),
314
+ * and `detectExtraMcpServers` advises on an edited one.
319
315
  */
320
316
  export function reconcileMcpJson(
321
317
  templatePath: string,
@@ -334,13 +330,8 @@ export function reconcileMcpJson(
334
330
  return;
335
331
  }
336
332
 
337
- // Parse-or-sentinel idiom (see reconcileOpencodeJson): the throw stays out of the catch.
338
- let existing: JsonValue | null = null;
339
- try {
340
- existing = JSON.parse(fs.readFileSync(relDst, "utf-8")) as JsonValue;
341
- } catch {
342
- existing = null;
343
- }
333
+ const read = readJsonFile(relDst);
334
+ const existing = read.ok ? (read.value as JsonValue) : null;
344
335
  if (existing === null || typeof existing !== "object" || Array.isArray(existing)) {
345
336
  throw new Error(
346
337
  `[bkit] ${relDst} is malformed JSON — fix manually before running bkit install`,
@@ -351,12 +342,13 @@ export function reconcileMcpJson(
351
342
  const servers = existing.mcpServers;
352
343
  const serversObj =
353
344
  servers !== null && typeof servers === "object" && !Array.isArray(servers) ? servers : {};
354
- const inSync = Object.entries(owned).every(
355
- ([k, v]) => JSON.stringify(serversObj[k]) === JSON.stringify(v),
356
- );
345
+ const inSync = Object.entries(owned).every(([k, v]) => trackerEntryInSync(serversObj[k], v));
357
346
  if (inSync) return;
358
347
 
359
- const next = { ...existing, mcpServers: { ...serversObj, ...owned } };
348
+ const merged = Object.fromEntries(
349
+ Object.entries(owned).map(([k, v]) => [k, mergeTrackerEntry(serversObj[k], v)]),
350
+ );
351
+ const next = { ...existing, mcpServers: { ...serversObj, ...merged } };
360
352
  if (!dryRun) fs.writeFileSync(relDst, JSON.stringify(next, null, 2) + "\n", "utf-8");
361
353
  ws.writes.push({ path: relDst, action: "update" });
362
354
  }
@@ -5,6 +5,7 @@
5
5
 
6
6
  import * as fs from "node:fs";
7
7
  import * as path from "node:path";
8
+ import { parseJson } from "../../shared/json.js";
8
9
  import type { CloudAgents } from "../manifest.js";
9
10
  import type { ModuleContext } from "./index.js";
10
11
 
@@ -26,7 +27,9 @@ function setConsumerBkitField(field: string, value: string, dryRun: boolean): vo
26
27
  if (!fs.existsSync(pkgPath)) return;
27
28
  try {
28
29
  const raw = fs.readFileSync(pkgPath, "utf-8");
29
- const pkg = JSON.parse(raw) as Record<string, unknown>;
30
+ const parsed = parseJson(raw);
31
+ if (!parsed.ok) return;
32
+ const pkg = parsed.value as Record<string, unknown>;
30
33
  const bkit = (pkg.bkit ?? {}) as Record<string, unknown>;
31
34
  if (bkit[field] === value) return; // already set — avoid a no-op rewrite
32
35
  bkit[field] = value;
@@ -101,7 +104,7 @@ export function runCloudModule(ctx: ModuleContext): void {
101
104
  " - Adopt `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` as `.claude/hooks/bkit-cloud-bootstrap.sh` and edit it freely — the baseline runs `pnpm install` / `vale sync` and the gh login on each cloud session; add your own repo-specific steps (Supabase start, turbo prebuild, etc. — examples inlined). The `.claude/settings.json` SessionStart entry runs it only when present (`test -f … || true`).\n\n" +
102
105
  "IN CLAUDE APP (claude.ai/code → environment selector → + Add environment):\n" +
103
106
  " - Name: the repo name (e.g. `acme-web`) — one environment per repo, since secrets are per-repo.\n" +
104
- " - Setup script: paste from bkit's `cloud.md` § Setup script (installs vale + gh + corepack-pinned pnpm — exact versions live in cloud.md, not duplicated here).\n" +
107
+ " - Setup script: paste from bkit's `cloud.md` § Setup script (installs Node 24 + vale + gh + jq + corepack-pinned pnpm — exact versions live in cloud.md, not duplicated here).\n" +
105
108
  " - Environment variables: `BKIT_GH_TOKEN` (fine-grained for one owner, classic across owners — GitHub MCP).\n" +
106
109
  " - Tracker env vars (GitHub): `BKIT_GH_TOKEN` above is the only tracker credential — the GitHub MCP server sends it on every call, and the bootstrap hook signs `gh` in with it.\n" +
107
110
  " - Network access: `Trusted` (default). One environment per repo (secrets differ per repo); the setup script + variable *names* are identical across repos, only the values change. See cloud.md § Sharing across repos → Claude.",
@@ -13,14 +13,9 @@ import {
13
13
  } from "../../shared/package-roots.js";
14
14
  import { type IssueTracker, DEFAULT_ISSUE_TRACKER } from "../manifest.js";
15
15
  import { substituteWorkflow } from "../../render/trackers.js";
16
+ import { readInstallingVersion } from "../../shared/package-json.js";
16
17
  import type { ModuleContext } from "./index.js";
17
- import {
18
- BKIT_PREFIX,
19
- installFile,
20
- listMdFiles,
21
- readInstallingVersion,
22
- trackMirrorWrite,
23
- } from "./core.js";
18
+ import { BKIT_PREFIX, installFile, listMdFiles, removeOrphans, trackMirrorWrite } from "./core.js";
24
19
 
25
20
  /**
26
21
  * Convert a workflow orchestrator (`.bkit/core/workflows/*.md`) into a Codex SKILL.md.
@@ -93,8 +88,8 @@ export function renderCodexAgentsSkills(ctx: ModuleContext): string[] {
93
88
  const dest = ".codex/agents";
94
89
  if (!dryRun) ensureDir(dest);
95
90
  const files = listMdFiles(src, BKIT_PREFIX);
96
- // Destination basenames are .toml, so the orphan sweep has to compare on stem.
97
- const sourceStems = new Set(files.map((f) => f.replace(/\.md$/, "")));
91
+ // Destination basenames are .toml, so the orphan sweep compares on the .toml names.
92
+ const sourceNames = new Set(files.map((f) => f.replace(/\.md$/, ".toml")));
98
93
 
99
94
  for (const f of files) {
100
95
  const stem = f.replace(/\.md$/, "");
@@ -108,17 +103,10 @@ export function renderCodexAgentsSkills(ctx: ModuleContext): string[] {
108
103
  }
109
104
  }
110
105
 
111
- if (fs.existsSync(dest)) {
112
- for (const f of fs.readdirSync(dest)) {
113
- if (!f.endsWith(".toml")) continue;
114
- if (!f.startsWith(BKIT_PREFIX)) continue;
115
- if (!sourceStems.has(f.replace(/\.toml$/, ""))) {
116
- const rel = path.join(dest, f);
117
- if (!dryRun) fs.rmSync(path.join(dest, f));
118
- console.log(`${logPrefix} ${tag}delete orphan: ${rel}`);
119
- trackMirrorWrite(ctx, rel, written);
120
- }
121
- }
106
+ for (const f of removeOrphans(dest, sourceNames, dryRun, BKIT_PREFIX, { extension: ".toml" })) {
107
+ const rel = path.join(dest, f);
108
+ console.log(`${logPrefix} ${tag}delete orphan: ${rel}`);
109
+ trackMirrorWrite(ctx, rel, written);
122
110
  }
123
111
  }
124
112
 
@@ -146,15 +134,13 @@ export function renderCodexAgentsSkills(ctx: ModuleContext): string[] {
146
134
 
147
135
  // Orphan sweep is bkit-prefix scoped: `.agents/skills/` is SHARED with third-party
148
136
  // skills installed via skills.sh, so anything not named bkit-* is off limits here.
149
- if (fs.existsSync(CODEX_SKILLS_DIR)) {
150
- for (const d of fs.readdirSync(CODEX_SKILLS_DIR)) {
151
- if (!d.startsWith(BKIT_PREFIX)) continue;
152
- if (sourceStems.has(d)) continue;
153
- const rel = path.join(CODEX_SKILLS_DIR, d);
154
- if (!dryRun) fs.rmSync(rel, { recursive: true, force: true });
155
- console.log(`${logPrefix} ${tag}delete orphan: ${rel}`);
156
- trackMirrorWrite(ctx, rel, written);
157
- }
137
+ const orphans = removeOrphans(CODEX_SKILLS_DIR, sourceStems, dryRun, BKIT_PREFIX, {
138
+ wholeFolders: true,
139
+ });
140
+ for (const d of orphans) {
141
+ const rel = path.join(CODEX_SKILLS_DIR, d);
142
+ console.log(`${logPrefix} ${tag}delete orphan: ${rel}`);
143
+ trackMirrorWrite(ctx, rel, written);
158
144
  }
159
145
  }
160
146