@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
@@ -1,16 +1,19 @@
1
1
  // commands/tips.ts — `bkit tips [--workflow=<name>] [--all]`: print the setup tips that
2
2
  // apply to this repo. Each workflow passes its name at its close and gets the one tip that
3
- // matters most there; bare `bkit tips` prints the top three. Local checks only, no
4
- // network; prints nothing when no tip fires; exits 0.
3
+ // matters most there (`audit` / `utility` for the audit agent and the ledger / roadmap
4
+ // updaters); bare `bkit tips` prints the top three. The star line closes bare and phase
5
+ // output unless `star` is in `bkit.ignoreAdvisories`. Local checks only, no network; prints
6
+ // nothing when no tip fires and no star line shows; exits 0.
5
7
 
6
- import type { ComplyPhase } from "../cli.js";
8
+ import type { TipsContext } from "../cli.js";
7
9
  import { collectTips, formatTips } from "../checks/tips/index.js";
8
10
 
9
11
  export function runTipsCommand(
10
12
  all: boolean,
11
- workflow: ComplyPhase | null,
13
+ workflow: TipsContext | null,
12
14
  cwd: string = process.cwd(),
13
15
  ): void {
14
- const output = formatTips(collectTips(cwd).tips, { all, workflow });
16
+ const { tips, star } = collectTips(cwd);
17
+ const output = formatTips(tips, { all, workflow, star });
15
18
  if (output) console.log(output);
16
19
  }
@@ -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,
@@ -29,6 +31,7 @@ import {
29
31
  type FlagValue,
30
32
  type RunContext,
31
33
  } from "../lib.js";
34
+ import { bkitVersionStatus, type BkitVersionStatus } from "../../shared/bkit-latest.js";
32
35
  import { TIMEOUTS } from "../../shared/timeouts.js";
33
36
  import { commitBookkeeping } from "./ledgers.js";
34
37
  import { acquireDevLock, lockRoot, releaseLock, resolveMonth, workflowLockPath } from "./locks.js";
@@ -45,9 +48,7 @@ import {
45
48
  import { str } from "./status.js";
46
49
 
47
50
  const REMOTE = "origin";
48
- const DEV = "dev";
49
51
  const UPSTREAM = `${REMOTE}/${DEV}`;
50
- const SHARED_BRANCHES = new Set([DEV, "main"]);
51
52
 
52
53
  /** Exit codes, distinct across verbs so a code means one thing anywhere in this noun. */
53
54
  export const EXIT_REFUSED = 3;
@@ -354,7 +355,17 @@ export function resolveRebase(
354
355
 
355
356
  const ANCHOR_OPEN = "<!-- bkit:anchor";
356
357
  const ANCHOR_CLOSE = "-->";
357
- export const ANCHOR_FIELDS = ["baseSha", "baseRef", "designPath", "designBaseSha"] as const;
358
+ /** Ends the visible line a stamp writes under the block when the doc came from an outdated bkit. */
359
+ const OUTDATED_MARK = "<!-- bkit:outdated -->";
360
+ const OUTDATED_LINE = new RegExp(`^.*${OUTDATED_MARK}\n(?:\n)?`, "gm");
361
+ export const ANCHOR_FIELDS = [
362
+ "baseSha",
363
+ "baseRef",
364
+ "designPath",
365
+ "designBaseSha",
366
+ "bkitVersion",
367
+ "bkitLatest",
368
+ ] as const;
358
369
  export type AnchorField = (typeof ANCHOR_FIELDS)[number];
359
370
 
360
371
  /** Lines of `text` with whether each sits inside an anchor block (a `sed '/open/,/close/'` range). */
@@ -390,20 +401,49 @@ export function readAnchor(text: string): Partial<Record<AnchorField, string>> {
390
401
  return out;
391
402
  }
392
403
 
393
- /** `text` with a fresh anchor block on top and every prior one removed, so re-stamping is idempotent. */
404
+ /**
405
+ * The bkit release a doc is being generated from, for its anchor: undefined when
406
+ * this repo has no `.bkit/version` pin (nothing to record). Asks the registry for
407
+ * the newest release at most once a day; offline leaves `latest` null.
408
+ */
409
+ export function anchorBkitStatus(cwd: string): BkitVersionStatus | undefined {
410
+ const status = bkitVersionStatus(
411
+ git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd,
412
+ git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]),
413
+ );
414
+ return status.version === null ? undefined : status;
415
+ }
416
+
417
+ /**
418
+ * `text` with a fresh anchor block on top and every prior one removed, so re-stamping
419
+ * is idempotent. With `bkit`, the block records the release the doc came from and the
420
+ * newest one (empty when unknown); an outdated release adds one visible warning line
421
+ * under the block, replaced or dropped by the next stamp like the block itself.
422
+ */
394
423
  export function stampAnchor(
395
424
  text: string,
396
425
  baseSha: string,
397
426
  design?: { path: string; baseSha: string },
398
427
  baseRef: string = UPSTREAM,
428
+ bkit?: BkitVersionStatus,
399
429
  ): string {
400
430
  const header = [ANCHOR_OPEN, `baseSha: ${baseSha}`, `baseRef: ${baseRef}`];
401
431
  if (design) header.push(`designPath: ${design.path}`, `designBaseSha: ${design.baseSha}`);
432
+ if (bkit) header.push(`bkitVersion: ${bkit.version ?? ""}`, `bkitLatest: ${bkit.latest ?? ""}`);
402
433
  header.push(ANCHOR_CLOSE);
403
- const body = anchorLines(text)
434
+ let body = anchorLines(text)
404
435
  .filter((l) => !l.inBlock)
405
436
  .map((l) => (l.last ? l.line : `${l.line}\n`))
406
- .join("");
437
+ .join("")
438
+ .replace(OUTDATED_LINE, "");
439
+ if (bkit?.outdated === true) {
440
+ // Blank lines on both sides of the warning, as prettier writes them.
441
+ header.push(
442
+ "",
443
+ `> **Outdated bkit:** generated with bkit ${bkit.version} while ${bkit.latest} was out, so its workflow and template text may be stale. Upgrade with \`pnpm bkit upgrade --latest\` and regenerate if that matters. ${OUTDATED_MARK}`,
444
+ );
445
+ body = `\n${body.replace(/^\n+/, "")}`;
446
+ }
407
447
  return `${header.join("\n")}\n${body}`;
408
448
  }
409
449
 
@@ -560,7 +600,7 @@ export function pushBranch(
560
600
  return notPushed(EXIT_SKIP_CI, { skipped: "skip-ci" });
561
601
  }
562
602
  }
563
- const shared = SHARED_BRANCHES.has(branch);
603
+ const shared = isSharedBranch(branch);
564
604
  if (mode === "abort" && !shared) {
565
605
  const pr =
566
606
  openPrFlag === undefined
@@ -693,7 +733,7 @@ function syncVerb(ctx: RunContext): number {
693
733
  ctx.log("no branch checked out (detached HEAD) — cannot merge dev's docs");
694
734
  return EXIT_DETACHED;
695
735
  }
696
- if (!SHARED_BRANCHES.has(branch) && docsBehind > 0) {
736
+ if (!isSharedBranch(branch) && docsBehind > 0) {
697
737
  ctx.log(`docs/ is ${docsBehind} commit(s) behind ${UPSTREAM} — merging it in`);
698
738
  if (!quietGit(top, ["merge", "--no-edit", UPSTREAM]).ok) {
699
739
  const outcome = resolveDocsMerge(top);
@@ -1191,8 +1231,10 @@ function anchorStampVerb(ctx: RunContext): number {
1191
1231
  baseSha: readAnchor(fs.readFileSync(designFile, "utf-8")).baseSha ?? "",
1192
1232
  }
1193
1233
  : undefined;
1234
+ const bkit = anchorBkitStatus(ctx.cwd);
1235
+ if (bkit?.advisory) ctx.log(bkit.advisory);
1194
1236
  const before = fs.readFileSync(file, "utf-8");
1195
- const after = stampAnchor(before, baseSha, design, baseRef);
1237
+ const after = stampAnchor(before, baseSha, design, baseRef, bkit);
1196
1238
  // Temp file + rename: a crash mid-write never leaves a half-stamped doc.
1197
1239
  const tmp = `${file}.bkit-anchor.tmp`;
1198
1240
  fs.writeFileSync(tmp, after);
@@ -1203,6 +1245,10 @@ function anchorStampVerb(ctx: RunContext): number {
1203
1245
  baseRef,
1204
1246
  designPath: design?.path ?? null,
1205
1247
  designBaseSha: design?.baseSha ?? null,
1248
+ bkitVersion: bkit?.version ?? null,
1249
+ bkitLatest: bkit?.latest ?? null,
1250
+ bkitOutdated: bkit?.outdated ?? null,
1251
+ bkitAdvisory: bkit?.advisory ?? null,
1206
1252
  changed: before !== after,
1207
1253
  });
1208
1254
  return EXIT.OK;
@@ -1221,7 +1267,7 @@ function anchorReadVerb(ctx: RunContext): number {
1221
1267
  ctx.emit({ ...fields, value: null, skip: reason, landed: null });
1222
1268
  return EXIT_ANCHOR_SKIP;
1223
1269
  };
1224
- const none = { baseSha: null, baseRef: null, designPath: null, designBaseSha: null };
1270
+ const none = Object.fromEntries(ANCHOR_FIELDS.map((f) => [f, null]));
1225
1271
  if (!fs.statSync(file, { throwIfNoEntry: false })?.isFile()) {
1226
1272
  if (against !== undefined) return skip("no-file", `no ${rel} — nothing to check`, none);
1227
1273
  ctx.log(`${rel} not found`);
@@ -1455,7 +1501,7 @@ export const branchesCommand: CommandSpec = {
1455
1501
  },
1456
1502
  "anchor-stamp": {
1457
1503
  summary:
1458
- "Put a <!-- bkit:anchor --> block recording the base commit on top of a design/plan doc or audit report (idempotent).",
1504
+ "Put a <!-- bkit:anchor --> block recording the base commit and bkit release on top of a design/plan doc or audit report (idempotent).",
1459
1505
  flags: [
1460
1506
  { name: "file", type: "string", required: true, help: "doc to stamp (must exist)" },
1461
1507
  {
@@ -1482,6 +1528,12 @@ export const branchesCommand: CommandSpec = {
1482
1528
  designPath: "design path stamped (null when none)",
1483
1529
  designBaseSha:
1484
1530
  "the design doc's baseSha stamped (null when none; empty when it had no anchor)",
1531
+ bkitVersion:
1532
+ "the .bkit/version pin stamped (null when unpinned: no bkit fields are stamped then)",
1533
+ bkitLatest: "newest published bkit stamped (null when unknown: stamped empty)",
1534
+ bkitOutdated:
1535
+ "true when bkitVersion is older than bkitLatest: a visible warning line is stamped under the block (null when unknown)",
1536
+ bkitAdvisory: "one warning line when bkitOutdated, else null",
1485
1537
  changed: "false when the doc already carried exactly this block",
1486
1538
  },
1487
1539
  exitCodes: { [EXIT_NO_FILE]: "--file is missing or not a file" },
@@ -1508,6 +1560,8 @@ export const branchesCommand: CommandSpec = {
1508
1560
  baseRef: "anchor baseRef (null when absent)",
1509
1561
  designPath: "anchor designPath (null when absent)",
1510
1562
  designBaseSha: "anchor designBaseSha (null when absent)",
1563
+ bkitVersion: "anchor bkitVersion (null when absent)",
1564
+ bkitLatest: "anchor bkitLatest (null when absent)",
1511
1565
  value: "the --field value (null when absent or no --field)",
1512
1566
  skip: "with --against: no-file | no-anchor | unreachable | nothing-landed (null = run the check)",
1513
1567
  landed: "with --against: paths changed between baseSha and the ref",
@@ -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
 
@@ -4,14 +4,15 @@
4
4
  // `owner/repo` comes from `gh repo view`; when gh is missing, unauthed, or
5
5
  // answers nothing, from the `origin` remote URL instead (the MCP fallback the
6
6
  // workflows already describe: "parse git remote"). The current branch, how far it
7
- // trails `origin/dev`, the main checkout, and the bkit binary every later block
8
- // calls ride along so Step 1 is one call.
7
+ // trails `origin/dev`, the main checkout, the bkit binary every later block calls,
8
+ // and whether that bkit is behind the newest release ride along so Step 1 is one call.
9
9
 
10
10
  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
+ import { bkitVersionStatus } from "../../shared/bkit-latest.js";
15
16
 
16
17
  /** Exit code: neither gh nor the origin remote named an owner/repo. */
17
18
  export const EXIT_NO_REPO = 3;
@@ -122,6 +123,13 @@ export const repoCommand: CommandSpec = {
122
123
  repoRoot: "the main checkout (the same from any worktree)",
123
124
  bkit: "the bkit binary the workflow blocks call: <repoRoot>/node_modules/.bin/bkit, else `bkit` on PATH",
124
125
  outboxRoot: "<git common dir>/bkit-outbox: per-run scratch files, never committed",
126
+ bkitVersion:
127
+ ".bkit/version pinnedVersion: the release this repo's bkit files came from (null when unpinned)",
128
+ bkitLatest:
129
+ "newest published @cbartens/bkit, asked at most once a day (null when offline, opted out via BKIT_NO_UPDATE_CHECK, or unpinned)",
130
+ bkitOutdated:
131
+ "true when bkitVersion is older than bkitLatest (null when either is unknown)",
132
+ bkitAdvisory: "one line to show the user when bkitOutdated, else null",
125
133
  },
126
134
  exitCodes: {
127
135
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -129,7 +137,7 @@ export const repoCommand: CommandSpec = {
129
137
  },
130
138
  run: (ctx) => {
131
139
  if (ctx.flags.fetch === true) {
132
- const res = runGit(ctx.cwd, ["fetch", "origin", "dev"]);
140
+ const res = runGit(ctx.cwd, ["fetch", "origin", DEV]);
133
141
  if (!res.ok)
134
142
  ctx.log(
135
143
  `git fetch origin dev failed — behindDev is as of the last fetch: ${res.stderr}`,
@@ -156,6 +164,8 @@ export const repoCommand: CommandSpec = {
156
164
  }
157
165
  const root = repoRoot(ctx.cwd);
158
166
  const common = git(ctx.cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
167
+ const latest = bkitVersionStatus(root, common);
168
+ if (latest.advisory !== null) ctx.log(latest.advisory);
159
169
  ctx.emit({
160
170
  ...resolved,
161
171
  owner,
@@ -165,6 +175,10 @@ export const repoCommand: CommandSpec = {
165
175
  repoRoot: root,
166
176
  bkit: resolveBkitBinary(root),
167
177
  outboxRoot: path.join(common ?? path.join(root, ".git"), "bkit-outbox"),
178
+ bkitVersion: latest.version,
179
+ bkitLatest: latest.latest,
180
+ bkitOutdated: latest.outdated,
181
+ bkitAdvisory: latest.advisory,
168
182
  });
169
183
  if (branch === null && ctx.flags.allowDetached !== true) {
170
184
  ctx.log("HEAD is detached — no current branch");
@@ -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;