@cbartens/bkit 5.2.4 → 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 (221) hide show
  1. package/.bkit/README.md +26 -11
  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 +25 -10
  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 +12 -6
  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 +106 -17
  15. package/.bkit/core/.bkit/trackers.md +47 -1
  16. package/.bkit/core/.bkit/workflows.md +44 -43
  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-adoption.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -10
  22. package/.bkit/core/docs/templates/bkit-audit-llm.md +20 -14
  23. package/.bkit/core/docs/templates/bkit-audit-prompts.md +2 -2
  24. package/.bkit/core/docs/templates/bkit-audit-red-team.md +10 -8
  25. package/.bkit/core/docs/templates/bkit-audit-security.md +3 -3
  26. package/.bkit/core/docs/templates/bkit-audit-testing.md +4 -3
  27. package/.bkit/core/docs/templates/bkit-plan.md +8 -6
  28. package/.bkit/core/engine/checks/after/auth.ts +9 -9
  29. package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
  30. package/.bkit/core/engine/checks/after/github.ts +29 -120
  31. package/.bkit/core/engine/checks/after/index.ts +2 -2
  32. package/.bkit/core/engine/checks/after/managed.ts +8 -28
  33. package/.bkit/core/engine/checks/after/tools.ts +3 -15
  34. package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
  35. package/.bkit/core/engine/checks/before/index.ts +7 -43
  36. package/.bkit/core/engine/checks/before/mcp.ts +17 -8
  37. package/.bkit/core/engine/checks/before/repo.ts +9 -12
  38. package/.bkit/core/engine/checks/status-holes.ts +4 -5
  39. package/.bkit/core/engine/checks/tips/catalogue.ts +60 -24
  40. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  41. package/.bkit/core/engine/checks/tips/index.ts +37 -8
  42. package/.bkit/core/engine/cli.ts +39 -16
  43. package/.bkit/core/engine/commands/analysis.ts +36 -26
  44. package/.bkit/core/engine/commands/comply.ts +17 -16
  45. package/.bkit/core/engine/commands/harvest.ts +12 -12
  46. package/.bkit/core/engine/commands/install/doctor.ts +57 -28
  47. package/.bkit/core/engine/commands/install/install.ts +62 -126
  48. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  49. package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
  50. package/.bkit/core/engine/commands/lib.ts +35 -10
  51. package/.bkit/core/engine/commands/tips.ts +8 -5
  52. package/.bkit/core/engine/commands/workflow/branches.ts +4 -4
  53. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  54. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  55. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  56. package/.bkit/core/engine/commands/workflow/prs.ts +4 -2
  57. package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
  58. package/.bkit/core/engine/commands/workflow/roadmap.ts +4 -3
  59. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  60. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  61. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  62. package/.bkit/core/engine/commands/workflow/workflows.ts +15 -14
  63. package/.bkit/core/engine/commands/workflow/workstreams.ts +2 -1
  64. package/.bkit/core/engine/commands/workflow/worktrees.ts +13 -5
  65. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  66. package/.bkit/core/engine/install/manifest.ts +14 -7
  67. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  68. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  69. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  70. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  71. package/.bkit/core/engine/install/modules/core.ts +91 -70
  72. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  73. package/.bkit/core/engine/install/modules/index.ts +7 -1
  74. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  75. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  76. package/.bkit/core/engine/install/placeholders.ts +3 -18
  77. package/.bkit/core/engine/install/write.ts +59 -12
  78. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  79. package/.bkit/core/engine/render/hosts.ts +47 -67
  80. package/.bkit/core/engine/render/models.ts +29 -11
  81. package/.bkit/core/engine/shared/branches.ts +13 -0
  82. package/.bkit/core/engine/shared/egress.ts +3 -3
  83. package/.bkit/core/engine/shared/json.ts +18 -1
  84. package/.bkit/core/engine/shared/package-json.ts +63 -0
  85. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  86. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  87. package/.bkit/core/engine/shared/settings.ts +36 -0
  88. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  89. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  90. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  91. package/.bkit/core/prompts/bkit-audit-generate.md +60 -7
  92. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  93. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  94. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  95. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  96. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  97. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  98. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  99. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  100. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  101. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  102. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  103. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  104. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  105. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  106. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  107. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  108. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  109. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  110. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  111. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  112. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  113. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  114. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  115. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  116. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  117. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  118. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  119. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  120. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  121. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  122. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  123. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  124. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  125. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  126. package/.bkit/core/workflows/bkit-build.md +3 -3
  127. package/.bkit/core/workflows/bkit-debug.md +69 -33
  128. package/.bkit/core/workflows/bkit-design.md +2 -2
  129. package/.bkit/core/workflows/bkit-plan.md +11 -4
  130. package/.bkit/core/workflows/bkit-ship.md +5 -5
  131. package/.bkit/shared/.claude/bkit-cloud.md +46 -13
  132. package/.bkit/shared/.claude/settings.json +18 -0
  133. package/.bkit/shared/.cursor/mcp.json +2 -1
  134. package/.bkit/shared/.opencode/opencode.json +19 -1
  135. package/.bkit/shared/docs/deployments.md +20 -4
  136. package/.bkit/shared/docs/security.md +8 -6
  137. package/.bkit/shared/docs/testing.md +9 -5
  138. package/.bkit/templates/.cursor/Dockerfile +30 -16
  139. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  140. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  141. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  142. package/.bkit/templates/.github/renovate.json5 +91 -12
  143. package/.bkit/templates/.github/workflows/bkit-ci.yml +66 -53
  144. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  145. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  146. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  147. package/.bkit/templates/.husky/pre-push +8 -3
  148. package/.bkit/templates/.oxlintrc.json +21 -0
  149. package/.bkit/templates/docs/capabilities.md +1 -1
  150. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  151. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  152. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  153. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  154. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  155. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  156. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  157. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  158. package/CHANGELOG.md +50 -3
  159. package/README.md +258 -129
  160. package/dist/checks/after/auth.js +10 -11
  161. package/dist/checks/after/ci-yml.js +11 -14
  162. package/dist/checks/after/github.js +32 -125
  163. package/dist/checks/after/index.js +3 -2
  164. package/dist/checks/after/managed.js +8 -24
  165. package/dist/checks/after/tools.js +3 -16
  166. package/dist/checks/before/context-fetch.js +1 -21
  167. package/dist/checks/before/index.js +6 -42
  168. package/dist/checks/before/mcp.js +14 -9
  169. package/dist/checks/before/repo.js +8 -11
  170. package/dist/checks/status-holes.js +5 -6
  171. package/dist/checks/tips/catalogue.js +51 -18
  172. package/dist/checks/tips/detect.js +41 -2
  173. package/dist/checks/tips/index.js +25 -5
  174. package/dist/cli.js +34 -14
  175. package/dist/commands/analysis.js +21 -5
  176. package/dist/commands/comply.js +20 -18
  177. package/dist/commands/harvest.js +12 -13
  178. package/dist/commands/install/doctor.js +55 -23
  179. package/dist/commands/install/install.js +62 -118
  180. package/dist/commands/install/uninstall.js +165 -31
  181. package/dist/commands/install/upgrade.js +46 -39
  182. package/dist/commands/lib.js +32 -10
  183. package/dist/commands/tips.js +6 -3
  184. package/dist/commands/workflow/branches.js +3 -5
  185. package/dist/commands/workflow/counters.js +17 -7
  186. package/dist/commands/workflow/fids.js +39 -0
  187. package/dist/commands/workflow/ledgers.js +3 -1
  188. package/dist/commands/workflow/prs.js +3 -3
  189. package/dist/commands/workflow/repo.js +2 -2
  190. package/dist/commands/workflow/roadmap.js +4 -4
  191. package/dist/commands/workflow/runs.js +5 -5
  192. package/dist/commands/workflow/steps.js +1 -0
  193. package/dist/commands/workflow/tests.js +16 -3
  194. package/dist/commands/workflow/workflows.js +15 -15
  195. package/dist/commands/workflow/workstreams.js +2 -1
  196. package/dist/commands/workflow/worktrees.js +4 -5
  197. package/dist/install/cloud-env.js +10 -23
  198. package/dist/install/manifest.js +14 -7
  199. package/dist/install/modules/antigravity.js +15 -26
  200. package/dist/install/modules/claude.js +17 -21
  201. package/dist/install/modules/cloud.js +6 -2
  202. package/dist/install/modules/codex.js +15 -29
  203. package/dist/install/modules/core.js +82 -63
  204. package/dist/install/modules/cursor.js +6 -9
  205. package/dist/install/modules/index.js +6 -1
  206. package/dist/install/modules/opencode.js +41 -72
  207. package/dist/install/network-allowlist.js +62 -0
  208. package/dist/install/placeholders.js +3 -16
  209. package/dist/install/write.js +55 -15
  210. package/dist/ledgers/telemetry.js +5 -4
  211. package/dist/render/hosts.js +30 -55
  212. package/dist/render/models.js +20 -9
  213. package/dist/shared/branches.js +11 -0
  214. package/dist/shared/egress.js +0 -2
  215. package/dist/shared/json.js +14 -0
  216. package/dist/shared/package-json.js +61 -0
  217. package/dist/shared/package-roots.js +0 -8
  218. package/dist/shared/protected-paths.js +5 -122
  219. package/dist/shared/settings.js +18 -1
  220. package/package.json +21 -17
  221. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -19,8 +19,10 @@ import { gitEnv } from "../../ledgers/telemetry.js";
19
19
  import {
20
20
  bodySkipToken,
21
21
  CommandError,
22
+ DEV,
22
23
  EXIT,
23
24
  git,
25
+ isSharedBranch,
24
26
  parseJson,
25
27
  repoRoot,
26
28
  runGit,
@@ -46,9 +48,7 @@ import {
46
48
  import { str } from "./status.js";
47
49
 
48
50
  const REMOTE = "origin";
49
- const DEV = "dev";
50
51
  const UPSTREAM = `${REMOTE}/${DEV}`;
51
- const SHARED_BRANCHES = new Set([DEV, "main"]);
52
52
 
53
53
  /** Exit codes, distinct across verbs so a code means one thing anywhere in this noun. */
54
54
  export const EXIT_REFUSED = 3;
@@ -600,7 +600,7 @@ export function pushBranch(
600
600
  return notPushed(EXIT_SKIP_CI, { skipped: "skip-ci" });
601
601
  }
602
602
  }
603
- const shared = SHARED_BRANCHES.has(branch);
603
+ const shared = isSharedBranch(branch);
604
604
  if (mode === "abort" && !shared) {
605
605
  const pr =
606
606
  openPrFlag === undefined
@@ -733,7 +733,7 @@ function syncVerb(ctx: RunContext): number {
733
733
  ctx.log("no branch checked out (detached HEAD) — cannot merge dev's docs");
734
734
  return EXIT_DETACHED;
735
735
  }
736
- if (!SHARED_BRANCHES.has(branch) && docsBehind > 0) {
736
+ if (!isSharedBranch(branch) && docsBehind > 0) {
737
737
  ctx.log(`docs/ is ${docsBehind} commit(s) behind ${UPSTREAM} — merging it in`);
738
738
  if (!quietGit(top, ["merge", "--no-edit", UPSTREAM]).ok) {
739
739
  const outcome = resolveDocsMerge(top);
@@ -57,23 +57,32 @@ const nonNegativeInt = (v: FlagValue, flag: string): number => {
57
57
  return Number(s);
58
58
  };
59
59
 
60
- /** `--of=<step>:<position>` over `--file` / `--workflow`: the counter at that position. */
60
+ /**
61
+ * `--of=<step>:<position>` over `--file` / `--workflow`: the counter at that position.
62
+ * `--of=<step>,<step>...:count` sums the DONE rows of every listed step.
63
+ */
61
64
  function derivedOf(ctx: RunContext): number {
62
- const [step, position] = String(ctx.flags.of).split(":");
63
- if (!step || !["next", "current", "count"].includes(position ?? ""))
64
- throw new CommandError(EXIT.USAGE, "--of must be <step>:<next|current|count>");
65
+ const [list, position] = String(ctx.flags.of).split(":");
66
+ const steps = (list ?? "").split(",");
67
+ if (steps.some((s) => s === "") || !["next", "current", "count"].includes(position ?? ""))
68
+ throw new CommandError(EXIT.USAGE, "--of must be <step>[,<step>...]:<next|current|count>");
69
+ if (steps.length > 1 && (position !== "count" || new Set(steps).size !== steps.length))
70
+ throw new CommandError(EXIT.USAGE, "--of with several steps takes distinct steps and :count");
65
71
  if (ctx.flags.file === undefined || ctx.flags.workflow === undefined)
66
72
  throw new CommandError(EXIT.USAGE, "--of needs --file and --workflow");
67
- const count = activeDoneSteps(
68
- readRuns(statusFile(ctx)),
69
- String(ctx.flags.workflow),
70
- { step, subPlan: positiveInt(ctx.flags.subPlan, "sub-plan") },
71
- str(ctx.flags.since),
72
- ).length;
73
+ const runs = readRuns(statusFile(ctx));
74
+ const subPlan = positiveInt(ctx.flags.subPlan, "sub-plan");
75
+ const count = steps.reduce(
76
+ (n, step) =>
77
+ n +
78
+ activeDoneSteps(runs, String(ctx.flags.workflow), { step, subPlan }, str(ctx.flags.since))
79
+ .length,
80
+ 0,
81
+ );
73
82
  if (position === "current" && count === 0)
74
83
  throw new CommandError(
75
84
  EXIT_NO_OWN_ROW,
76
- `${step}: no DONE row in the active run — the step's own row is missing`,
85
+ `${steps[0]}: no DONE row in the active run — the step's own row is missing`,
77
86
  );
78
87
  return position === "next" ? count + 1 : count;
79
88
  }
@@ -160,7 +169,7 @@ export const countersCommand: CommandSpec = {
160
169
  {
161
170
  name: "of",
162
171
  type: "string",
163
- help: "<step>:<next|current|count> — derive the value from --file (active run)",
172
+ help: "<step>:<next|current|count> — derive the value from --file (active run); <step>,<step>...:count sums the listed steps",
164
173
  },
165
174
  { ...FILE_FLAG, required: false, help: "status.jsonl, with --of" },
166
175
  { ...WORKFLOW_FLAG, required: false, help: "workflow, with --of" },
@@ -53,6 +53,27 @@ export function logged(root: string, issue: string): string[] {
53
53
  return [...found].sort();
54
54
  }
55
55
 
56
+ /**
57
+ * The canonical design doc for a feature, `docs/plans/{YYYYMM}/{fid}-design.md`: the
58
+ * `month` bucket first, else the newest bucket holding one. null when none exists.
59
+ */
60
+ export function designDoc(
61
+ root: string,
62
+ fid: string,
63
+ month?: string,
64
+ ): { month: string; path: string } | null {
65
+ const plans = path.join(root, "docs", "plans");
66
+ if (!fs.existsSync(plans)) return null;
67
+ const at = (m: string) => fs.existsSync(path.join(plans, m, `${fid}-design.md`));
68
+ const months = fs
69
+ .readdirSync(plans)
70
+ .filter((m) => /^[0-9]{6}$/.test(m))
71
+ .sort()
72
+ .reverse();
73
+ const hit = month !== undefined && months.includes(month) && at(month) ? month : months.find(at);
74
+ return hit === undefined ? null : { month: hit, path: `docs/plans/${hit}/${fid}-design.md` };
75
+ }
76
+
56
77
  /** `package.json` `bkit.issueTracker` at the main checkout (cwd outside git); default `none`. */
57
78
  export function readIssueTracker(cwd: string): IssueTracker {
58
79
  const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
@@ -214,6 +235,31 @@ export const fidsCommand: CommandSpec = {
214
235
  return EXIT.OK;
215
236
  },
216
237
  },
238
+ design: {
239
+ summary:
240
+ "The feature's own design doc, docs/plans/{YYYYMM}/{FID}-design.md: exit 0 found, exit 1 none.",
241
+ flags: [
242
+ { name: "fid", type: "string", required: true, help: "feature id" },
243
+ {
244
+ name: "month",
245
+ type: "string",
246
+ help: "YYYYMM bucket checked first; else the newest bucket holding the doc",
247
+ },
248
+ ],
249
+ output: {
250
+ fid: "the FID when its design doc exists, else null",
251
+ month: "the bucket holding it, else null",
252
+ path: "repo-relative path, else null",
253
+ },
254
+ run: (ctx) => {
255
+ const fid = String(ctx.flags.fid);
256
+ const hit = designDoc(repoRoot(ctx.cwd), fid, str(ctx.flags.month));
257
+ ctx.emit(
258
+ hit ? { fid, month: hit.month, path: hit.path } : { fid: null, month: null, path: null },
259
+ );
260
+ return hit ? EXIT.OK : EXIT.NO;
261
+ },
262
+ },
217
263
  find: {
218
264
  summary: "The feature already logged for an issue: exit 0 one, exit 1 none, exit 4 several.",
219
265
  flags: [
@@ -91,7 +91,9 @@ function gitRaw(cwd: string, args: string[]): GitResult {
91
91
  env: gitEnv(),
92
92
  maxBuffer: 1 << 28,
93
93
  });
94
- return { status: res.status, stdout: res.stdout ?? "", stderr: (res.stderr ?? "").trim() };
94
+ // A spawn error is never a success: the child can exit 0 before ENOBUFS kills it.
95
+ const status = res.error && res.status === 0 ? 1 : res.status;
96
+ return { status, stdout: res.stdout ?? "", stderr: (res.stderr ?? "").trim() };
95
97
  }
96
98
 
97
99
  const nulList = (out: string) => out.split("\0").filter((p) => p !== "");
@@ -16,9 +16,11 @@ import { appendLine, statusTimestamp, type StatusRow } from "../../ledgers/statu
16
16
  import {
17
17
  bodySkipToken,
18
18
  CommandError,
19
+ DEV,
19
20
  EXIT,
20
21
  ghUnavailable,
21
22
  git,
23
+ isSharedBranch,
22
24
  parseJson,
23
25
  repoRoot,
24
26
  runGh,
@@ -241,9 +243,9 @@ export function openPrFor(cwd: string, o: OpenInput, log: (m: string) => void):
241
243
  return { code: EXIT_SKIP_CI_TITLE, out: null };
242
244
  }
243
245
 
244
- const base = refFlag(o.base ?? "dev", "base");
246
+ const base = refFlag(o.base ?? DEV, "base");
245
247
  const head = o.head === undefined ? currentBranch(cwd) : refFlag(o.head, "head");
246
- if (head === base || head === "dev" || head === "main") {
248
+ if (head === base || isSharedBranch(head)) {
247
249
  throw new CommandError(EXIT.USAGE, `refusing to open a PR from "${head}" into "${base}"`);
248
250
  }
249
251
 
@@ -11,7 +11,7 @@ import * as fs from "node:fs";
11
11
  import * as path from "node:path";
12
12
 
13
13
  import { parseRemoteUrlToSlug } from "../../ledgers/telemetry.js";
14
- import { EXIT, git, repoRoot, runGit, runTool, type CommandSpec } from "../lib.js";
14
+ import { DEV, EXIT, git, repoRoot, runGit, runTool, type CommandSpec } from "../lib.js";
15
15
  import { bkitVersionStatus } from "../../shared/bkit-latest.js";
16
16
 
17
17
  /** Exit code: neither gh nor the origin remote named an owner/repo. */
@@ -137,7 +137,7 @@ export const repoCommand: CommandSpec = {
137
137
  },
138
138
  run: (ctx) => {
139
139
  if (ctx.flags.fetch === true) {
140
- const res = runGit(ctx.cwd, ["fetch", "origin", "dev"]);
140
+ const res = runGit(ctx.cwd, ["fetch", "origin", DEV]);
141
141
  if (!res.ok)
142
142
  ctx.log(
143
143
  `git fetch origin dev failed — behindDev is as of the last fetch: ${res.stderr}`,
@@ -22,6 +22,7 @@ import { compareTs, parse, resolveRepoSlug, validate } from "../../ledgers/telem
22
22
  import { readBkitVersion } from "../../install/version-file.js";
23
23
  import {
24
24
  CommandError,
25
+ DEV,
25
26
  EXIT,
26
27
  git,
27
28
  parseJson,
@@ -455,8 +456,8 @@ async function mirror(ctx: RunContext): Promise<number> {
455
456
  try {
456
457
  const prior = git(root, ["branch", "--show-current"]) ?? "";
457
458
  if (
458
- !runGit(root, ["checkout", "dev"]).ok ||
459
- !runGit(root, ["pull", "--ff-only", "origin", "dev"]).ok
459
+ !runGit(root, ["checkout", DEV]).ok ||
460
+ !runGit(root, ["pull", "--ff-only", "origin", DEV]).ok
460
461
  ) {
461
462
  if (prior) runGit(root, ["checkout", prior]);
462
463
  return done(false, "dev checkout / pull failed");
@@ -472,7 +473,7 @@ async function mirror(ctx: RunContext): Promise<number> {
472
473
  "--",
473
474
  ...ROADMAP_FILES,
474
475
  ]);
475
- const pushed = runGit(root, ["push", "origin", "dev"]).ok;
476
+ const pushed = runGit(root, ["push", "origin", DEV]).ok;
476
477
  if (!pushed) ctx.log("dev push failed — feat-side row already written");
477
478
  if (prior) runGit(root, ["checkout", prior]);
478
479
  return done(pushed, pushed ? null : "dev push failed");
@@ -28,8 +28,10 @@ import {
28
28
  bodySkipToken,
29
29
  commitMessage,
30
30
  CommandError,
31
+ DEV,
31
32
  EXIT,
32
33
  git,
34
+ isSharedBranch,
33
35
  parseJson,
34
36
  runGh,
35
37
  runGit,
@@ -247,7 +249,7 @@ export async function waitLoop(
247
249
  function currentPr(cwd: string, gh: Gh): { pr: string | null; missing: boolean } {
248
250
  const branch = git(cwd, ["branch", "--show-current"]);
249
251
  if (!branch) return { pr: null, missing: false };
250
- const res = gh(["pr", "list", "--head", branch, "--base", "dev", "--json", "number"]);
252
+ const res = gh(["pr", "list", "--head", branch, "--base", DEV, "--json", "number"]);
251
253
  if (res.missing) return { pr: null, missing: true };
252
254
  const n = obj(arr(res.ok ? jsonOrUndefined(res.stdout) : undefined)[0]).number;
253
255
  return { pr: typeof n === "number" ? String(n) : null, missing: false };
@@ -308,10 +310,9 @@ function pushCurrentBranch(cwd: string): boolean {
308
310
  const branch = git(cwd, ["branch", "--show-current"]);
309
311
  if (!branch) return false;
310
312
  // Shared branches never force; a feature branch is rewritten only by this run.
311
- const args =
312
- branch === "dev" || branch === "main"
313
- ? ["push", "origin", branch]
314
- : ["push", "--force-with-lease", "origin", branch];
313
+ const args = isSharedBranch(branch)
314
+ ? ["push", "origin", branch]
315
+ : ["push", "--force-with-lease", "origin", branch];
315
316
  return runGit(cwd, args).ok;
316
317
  }
317
318
 
@@ -1733,7 +1734,7 @@ async function runContext(ctx: RunContext): Promise<number> {
1733
1734
  mode: "CI_DEV",
1734
1735
  fid: arg,
1735
1736
  issueId: tracker === "none" ? null : issueIdOf(arg, "any"),
1736
- branch: "dev",
1737
+ branch: DEV,
1737
1738
  headSha: git(ctx.cwd, ["rev-parse", "origin/dev"]) ?? "",
1738
1739
  });
1739
1740
  return EXIT.OK;
@@ -1807,7 +1808,7 @@ async function runContext(ctx: RunContext): Promise<number> {
1807
1808
  async function runMirror(ctx: RunContext): Promise<number> {
1808
1809
  const f = ctx.flags;
1809
1810
  const head = String(f.head);
1810
- const branch = str(f.branch) ?? "dev";
1811
+ const branch = str(f.branch) ?? DEV;
1811
1812
  if (!branch) throw new CommandError(EXIT.USAGE, "--branch must not be empty");
1812
1813
  const o: MirrorOptions = {
1813
1814
  head,
@@ -302,6 +302,7 @@ export const ROW_FIELDS: Record<string, readonly RowField[]> = {
302
302
  "build/build-summary": ["attempt"],
303
303
  "debug/debug-run-tests": ["attempt", "scope"],
304
304
  "debug/context-fetch": ["attempt"],
305
+ "debug/debug-failure-reproduce": ["attempt"],
305
306
  "debug/debug-failure-diagnose": ["attempt", "strategy"],
306
307
  "debug/debug-failure-remediate": ["attempt", "strategy"],
307
308
  "debug/debug-failure-soak": ["attempt"],
@@ -614,6 +614,11 @@ export const testsCommand: CommandSpec = {
614
614
  repeatable: true,
615
615
  help: "candidate plan file; the first that exists is audited",
616
616
  },
617
+ {
618
+ name: "brief",
619
+ type: "string",
620
+ help: "the build input, audited when no plan file exists and it carries `**Task N:**` lines with `Test first:`",
621
+ },
617
622
  {
618
623
  name: "log",
619
624
  type: "string",
@@ -624,7 +629,7 @@ export const testsCommand: CommandSpec = {
624
629
  output: {
625
630
  enforced: "false when there is nothing to audit (reason says why)",
626
631
  reason: "why test-first is not enforced",
627
- plan: "the plan file audited",
632
+ plan: "the plan file audited (the brief when no plan file exists and it carries Test first lines)",
628
633
  gaps: "[{task, kind, detail}]: no-test-first | test-first-malformed | no-red | red-mismatch | red-evidence-missing | test-changed | not-green",
629
634
  log: "where the report was written (as given)",
630
635
  },
@@ -638,9 +643,14 @@ export const testsCommand: CommandSpec = {
638
643
  if (logArg === "") throw new CommandError(EXIT.USAGE, "--log must be non-empty");
639
644
  const log = path.resolve(ctx.cwd, logArg);
640
645
  const top = toplevel(ctx.cwd);
641
- const plan = (ctx.flags.plan as string[]).find((p) =>
642
- fs.existsSync(path.resolve(ctx.cwd, p)),
643
- );
646
+ const exists = (p: string) => fs.existsSync(path.resolve(ctx.cwd, p));
647
+ const planFile = (ctx.flags.plan as string[]).find(exists);
648
+ const briefArg = str(ctx.flags.brief);
649
+ const brief =
650
+ planFile === undefined && briefArg !== undefined && exists(briefArg)
651
+ ? briefArg
652
+ : undefined;
653
+ const plan = planFile ?? brief;
644
654
  const specs = plan
645
655
  ? readTestFirst(fs.readFileSync(path.resolve(ctx.cwd, plan), "utf-8"))
646
656
  : [];
@@ -648,7 +658,9 @@ export const testsCommand: CommandSpec = {
648
658
  plan === undefined
649
659
  ? "no plan file — the build runs from its brief"
650
660
  : !specs.some((s) => s.kind !== "missing")
651
- ? "the plan has no `Test first:` lines"
661
+ ? brief !== undefined
662
+ ? "no plan file, and the brief has no `**Task N:**` lines with `Test first:`"
663
+ : "the plan has no `Test first:` lines"
652
664
  : resolveGate(top, [BKIT_TEST_FILE_SCRIPT]) === null
653
665
  ? `\`${BKIT_TEST_FILE_SCRIPT}\` is not declared in package.json`
654
666
  : undefined;
@@ -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,
@@ -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(
@@ -1545,7 +1546,7 @@ export const workflowsCommand: CommandSpec = {
1545
1546
  const month = resolveMonth(root, fid, str(ctx.flags.month));
1546
1547
  const artifacts = artifactLinks(
1547
1548
  root,
1548
- str(ctx.flags.ref) ?? "dev",
1549
+ str(ctx.flags.ref) ?? DEV,
1549
1550
  month,
1550
1551
  fid,
1551
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(