@cbartens/bkit 5.2.4 → 5.4.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 (271) hide show
  1. package/.bkit/README.md +27 -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 +18 -1
  6. package/.bkit/core/.bkit/README.md +26 -10
  7. package/.bkit/core/.bkit/cloud.md +40 -39
  8. package/.bkit/core/.bkit/comparison.md +68 -345
  9. package/.bkit/core/.bkit/install.md +16 -9
  10. package/.bkit/core/.bkit/lite.md +73 -0
  11. package/.bkit/core/.bkit/pipeline.md +346 -0
  12. package/.bkit/core/.bkit/prompts.md +90 -74
  13. package/.bkit/core/.bkit/providers.md +42 -23
  14. package/.bkit/core/.bkit/templates.md +138 -19
  15. package/.bkit/core/.bkit/trackers.md +49 -4
  16. package/.bkit/core/.bkit/workflows.md +144 -123
  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 +3 -2
  21. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  22. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  23. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  25. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  26. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  28. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  30. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  31. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  32. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  34. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  35. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  36. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +26 -21
  37. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  39. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  40. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  41. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  42. package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
  43. package/.bkit/core/docs/templates/bkit-audit-llm.md +22 -15
  44. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  45. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  47. package/.bkit/core/docs/templates/bkit-audit-prompts.md +7 -7
  48. package/.bkit/core/docs/templates/bkit-audit-red-team.md +12 -9
  49. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  50. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-security.md +14 -12
  52. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-testing.md +10 -8
  54. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -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 -6
  67. package/.bkit/core/engine/checks/tips/catalogue.ts +76 -24
  68. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  69. package/.bkit/core/engine/checks/tips/index.ts +77 -26
  70. package/.bkit/core/engine/cli.ts +57 -27
  71. package/.bkit/core/engine/commands/analysis.ts +36 -26
  72. package/.bkit/core/engine/commands/comply.ts +42 -32
  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 +73 -130
  76. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  77. package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
  78. package/.bkit/core/engine/commands/land.ts +156 -0
  79. package/.bkit/core/engine/commands/lib.ts +45 -18
  80. package/.bkit/core/engine/commands/registry.ts +2 -0
  81. package/.bkit/core/engine/commands/tips.ts +12 -5
  82. package/.bkit/core/engine/commands/workflow/branches.ts +386 -286
  83. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  84. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  85. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  86. package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  88. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  89. package/.bkit/core/engine/commands/workflow/prs.ts +15 -4
  90. package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
  91. package/.bkit/core/engine/commands/workflow/roadmap.ts +49 -53
  92. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  93. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  94. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  95. package/.bkit/core/engine/commands/workflow/steps.ts +25 -15
  96. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  97. package/.bkit/core/engine/commands/workflow/workflows.ts +436 -267
  98. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -2
  99. package/.bkit/core/engine/commands/workflow/worktrees.ts +24 -6
  100. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  101. package/.bkit/core/engine/install/manifest.ts +14 -7
  102. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  103. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  104. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  105. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  106. package/.bkit/core/engine/install/modules/core.ts +106 -70
  107. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  108. package/.bkit/core/engine/install/modules/index.ts +7 -1
  109. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  110. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  111. package/.bkit/core/engine/install/placeholders.ts +16 -35
  112. package/.bkit/core/engine/install/write.ts +59 -12
  113. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  114. package/.bkit/core/engine/render/hosts.ts +47 -67
  115. package/.bkit/core/engine/render/models.ts +29 -11
  116. package/.bkit/core/engine/shared/branches.ts +13 -0
  117. package/.bkit/core/engine/shared/egress.ts +3 -3
  118. package/.bkit/core/engine/shared/json.ts +18 -1
  119. package/.bkit/core/engine/shared/package-json.ts +63 -0
  120. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  121. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  122. package/.bkit/core/engine/shared/settings.ts +44 -0
  123. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  124. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  125. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  126. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  127. package/.bkit/core/prompts/bkit-audit-generate.md +103 -7
  128. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  129. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  130. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  131. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  132. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  133. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  134. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  135. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  136. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  137. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  138. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  139. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  140. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  141. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  142. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  143. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  144. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  145. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  146. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  147. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  148. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  149. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  150. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  151. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  152. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  153. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  154. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  155. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  156. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  157. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  158. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  159. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  160. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  161. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  162. package/.bkit/core/workflows/bkit-auto.md +2 -2
  163. package/.bkit/core/workflows/bkit-build.md +10 -10
  164. package/.bkit/core/workflows/bkit-debug.md +80 -44
  165. package/.bkit/core/workflows/bkit-design.md +22 -13
  166. package/.bkit/core/workflows/bkit-plan.md +33 -16
  167. package/.bkit/core/workflows/bkit-ship.md +87 -98
  168. package/.bkit/shared/.claude/bkit-cloud.md +58 -25
  169. package/.bkit/shared/.claude/settings.json +19 -0
  170. package/.bkit/shared/.cursor/mcp.json +2 -1
  171. package/.bkit/shared/.opencode/opencode.json +19 -1
  172. package/.bkit/shared/docs/deployments.md +49 -29
  173. package/.bkit/shared/docs/security.md +8 -6
  174. package/.bkit/shared/docs/testing.md +9 -5
  175. package/.bkit/shared/gitignore +1 -2
  176. package/.bkit/templates/.cursor/Dockerfile +30 -16
  177. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  178. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  179. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  180. package/.bkit/templates/.github/renovate.json5 +91 -12
  181. package/.bkit/templates/.github/workflows/bkit-ci.yml +73 -55
  182. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  183. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  184. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  185. package/.bkit/templates/.husky/pre-commit +6 -0
  186. package/.bkit/templates/.husky/pre-push +15 -3
  187. package/.bkit/templates/.lintstagedrc.json +5 -1
  188. package/.bkit/templates/.oxlintrc.json +21 -0
  189. package/.bkit/templates/docs/capabilities.md +1 -1
  190. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  191. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  192. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  193. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  194. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  195. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  196. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  197. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  198. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  199. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  200. package/CHANGELOG.md +98 -3
  201. package/README.md +252 -122
  202. package/dist/checks/after/auth.js +10 -11
  203. package/dist/checks/after/ci-yml.js +11 -14
  204. package/dist/checks/after/github.js +32 -125
  205. package/dist/checks/after/index.js +3 -2
  206. package/dist/checks/after/managed.js +8 -24
  207. package/dist/checks/after/tools.js +3 -16
  208. package/dist/checks/before/context-fetch.js +1 -21
  209. package/dist/checks/before/index.js +6 -42
  210. package/dist/checks/before/mcp.js +14 -9
  211. package/dist/checks/before/repo.js +8 -11
  212. package/dist/checks/status-holes.js +5 -7
  213. package/dist/checks/tips/catalogue.js +65 -18
  214. package/dist/checks/tips/detect.js +41 -2
  215. package/dist/checks/tips/index.js +61 -25
  216. package/dist/cli.js +52 -26
  217. package/dist/commands/analysis.js +21 -5
  218. package/dist/commands/comply.js +40 -31
  219. package/dist/commands/harvest.js +12 -13
  220. package/dist/commands/install/doctor.js +55 -23
  221. package/dist/commands/install/install.js +72 -122
  222. package/dist/commands/install/uninstall.js +165 -31
  223. package/dist/commands/install/upgrade.js +46 -39
  224. package/dist/commands/land.js +129 -0
  225. package/dist/commands/lib.js +41 -16
  226. package/dist/commands/registry.js +2 -0
  227. package/dist/commands/tips.js +10 -3
  228. package/dist/commands/workflow/branches.js +303 -248
  229. package/dist/commands/workflow/counters.js +17 -7
  230. package/dist/commands/workflow/disk.js +452 -0
  231. package/dist/commands/workflow/fids.js +39 -0
  232. package/dist/commands/workflow/issues.js +63 -27
  233. package/dist/commands/workflow/ledgers.js +3 -1
  234. package/dist/commands/workflow/locks.js +35 -130
  235. package/dist/commands/workflow/prs.js +8 -5
  236. package/dist/commands/workflow/repo.js +2 -2
  237. package/dist/commands/workflow/roadmap.js +50 -57
  238. package/dist/commands/workflow/runs.js +5 -5
  239. package/dist/commands/workflow/runtime.js +3 -2
  240. package/dist/commands/workflow/status.js +32 -12
  241. package/dist/commands/workflow/steps.js +19 -11
  242. package/dist/commands/workflow/tests.js +16 -3
  243. package/dist/commands/workflow/workflows.js +390 -249
  244. package/dist/commands/workflow/workstreams.js +4 -2
  245. package/dist/commands/workflow/worktrees.js +15 -6
  246. package/dist/install/cloud-env.js +10 -23
  247. package/dist/install/manifest.js +14 -7
  248. package/dist/install/modules/antigravity.js +15 -26
  249. package/dist/install/modules/claude.js +17 -21
  250. package/dist/install/modules/cloud.js +6 -2
  251. package/dist/install/modules/codex.js +15 -29
  252. package/dist/install/modules/core.js +95 -63
  253. package/dist/install/modules/cursor.js +6 -9
  254. package/dist/install/modules/index.js +6 -1
  255. package/dist/install/modules/opencode.js +41 -72
  256. package/dist/install/network-allowlist.js +62 -0
  257. package/dist/install/placeholders.js +16 -35
  258. package/dist/install/write.js +55 -15
  259. package/dist/ledgers/telemetry.js +5 -4
  260. package/dist/render/hosts.js +30 -55
  261. package/dist/render/models.js +20 -9
  262. package/dist/shared/branches.js +11 -0
  263. package/dist/shared/egress.js +0 -2
  264. package/dist/shared/json.js +14 -0
  265. package/dist/shared/package-json.js +61 -0
  266. package/dist/shared/package-roots.js +0 -8
  267. package/dist/shared/protected-paths.js +5 -122
  268. package/dist/shared/settings.js +23 -1
  269. package/dist/shared/timeouts.js +8 -7
  270. package/package.json +21 -17
  271. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -1,6 +1,6 @@
1
1
  // bkit roadmap fold|feature|mirror — rewrite the generated region of
2
2
  // docs/roadmap.md from .bkit/issues.jsonl, its SOLE input; append a feature's
3
- // row; and copy a build / debug close's row to dev under the dev lock.
3
+ // row; and copy a build / debug close's row to dev through a throwaway checkout.
4
4
  //
5
5
  // The status block is a pure projection of the ledger, re-rendered in full, so
6
6
  // a close never parses the board back. The two `## Notes` blocks and the
@@ -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,
@@ -30,7 +31,7 @@ import {
30
31
  type CommandSpec,
31
32
  type RunContext,
32
33
  } from "../lib.js";
33
- import { acquireDevLock, releaseLock } from "./locks.js";
34
+ import { landDir, pushToDev } from "../land.js";
34
35
  import { str } from "./status.js";
35
36
 
36
37
  /** Roadmap status each workflow's close moves the feature to. */
@@ -413,17 +414,14 @@ function feature(ctx: RunContext): number {
413
414
  return ctx.flags.strict === true && !r.appended ? EXIT.NO : EXIT.OK;
414
415
  }
415
416
 
416
- /** Seconds the mirror waits for a busy dev lock before skipping. */
417
- export const MIRROR_DEV_LOCK_DEADLINE_S = 60;
418
-
419
417
  const ROADMAP_FILES = [".bkit/issues.jsonl", "docs/roadmap.md"];
420
418
 
421
419
  /**
422
- * Build / debug close: append the feature row in the worktree, then copy the
423
- * SAME row to `dev` in the main checkout under the dev lock — checkout dev,
424
- * fast-forward, append, commit the two roadmap files, push, return to the prior
425
- * branch. Skipped in adopt mode (the worktree IS the main checkout) and when the
426
- * dev lock stays busy. Fail-open throughout: the feat-side row is already written.
420
+ * Build / debug close: append the feature row in the worktree, then land the
421
+ * SAME row on `dev` through a throwaway origin/dev checkout (`pushToDev`). The
422
+ * main checkout is never touched. Skipped when the run's own checkout is on dev
423
+ * (the row rides that branch's commit). Fail-open throughout: the feat-side row
424
+ * is already written and reaches dev with ship's merge.
427
425
  */
428
426
  async function mirror(ctx: RunContext): Promise<number> {
429
427
  const workflow = String(ctx.flags.workflow);
@@ -437,47 +435,45 @@ async function mirror(ctx: RunContext): Promise<number> {
437
435
  ctx.emit({ row: feat.row, appended: feat.appended, mirrored, skipped });
438
436
  return EXIT.OK;
439
437
  };
440
- if (path.resolve(wt) === path.resolve(root)) return done(false, "adopt mode");
441
-
442
- let lock: { path: string; token: string };
443
- try {
444
- lock = await acquireDevLock({
445
- cwd: root,
446
- workflow,
447
- fid,
448
- deadlineS: MIRROR_DEV_LOCK_DEADLINE_S,
449
- log: ctx.log,
450
- });
451
- } catch (err) {
452
- // A busy lock skips the mirror; it never fails the close.
453
- return done(false, `dev lock busy: ${(err as Error).message}`);
454
- }
455
- try {
456
- const prior = git(root, ["branch", "--show-current"]) ?? "";
457
- if (
458
- !runGit(root, ["checkout", "dev"]).ok ||
459
- !runGit(root, ["pull", "--ff-only", "origin", "dev"]).ok
460
- ) {
461
- if (prior) runGit(root, ["checkout", prior]);
462
- return done(false, "dev checkout / pull failed");
463
- }
464
- const onDev = appendFeature(root, { row: JSON.stringify(feat.row) }, ctx.log);
465
- if (!onDev.appended) ctx.log("roadmap row skipped on dev");
466
- runGit(root, ["add", "--", ...ROADMAP_FILES]);
467
- runGit(root, [
468
- "commit",
469
- "--allow-empty",
470
- "-m",
471
- `docs(${fid}): ${workflow} roadmap update bkit [skip ci]`,
472
- "--",
473
- ...ROADMAP_FILES,
474
- ]);
475
- const pushed = runGit(root, ["push", "origin", "dev"]).ok;
476
- if (!pushed) ctx.log("dev push failed — feat-side row already written");
477
- if (prior) runGit(root, ["checkout", prior]);
478
- return done(pushed, pushed ? null : "dev push failed");
479
- } finally {
480
- releaseLock(lock.path, { workflow, fid, token: lock.token });
438
+ if (git(wt, ["branch", "--show-current"]) === DEV) return done(false, "on dev");
439
+
440
+ // A build that commits nothing pushes origin/dev back to itself, which git
441
+ // reports as success — so a landing counts only when this attempt committed.
442
+ let committed = "";
443
+ const res = await pushToDev({
444
+ root,
445
+ dir: landDir(root, fid),
446
+ build: (dir) => {
447
+ committed = "";
448
+ if (!appendFeature(dir, { row: JSON.stringify(feat.row) }, ctx.log).appended) {
449
+ committed = "row not appended on dev";
450
+ return;
451
+ }
452
+ runGit(dir, ["add", "--", ...ROADMAP_FILES]);
453
+ const made = runGit(dir, [
454
+ "commit",
455
+ "-m",
456
+ `docs(${fid}): ${workflow} roadmap update bkit [skip ci]`,
457
+ "--",
458
+ ...ROADMAP_FILES,
459
+ ]);
460
+ if (!made.ok) committed = `roadmap commit failed: ${made.stderr || made.stdout}`;
461
+ },
462
+ log: ctx.log,
463
+ });
464
+ switch (res.kind) {
465
+ case "landed":
466
+ return committed ? done(false, committed) : done(true, null);
467
+ case "refused":
468
+ return done(false, `dev push refused: ${res.stderr}`);
469
+ case "push-failed":
470
+ return done(false, `dev push failed: ${res.stderr}`);
471
+ case "exhausted":
472
+ return done(false, `dev moved before each of ${res.attempts} pushes`);
473
+ case "fetch-failed":
474
+ return done(false, `fetch of dev failed: ${res.stderr}`);
475
+ case "setup-failed":
476
+ return done(false, `throwaway checkout failed: ${res.stderr}`);
481
477
  }
482
478
  }
483
479
 
@@ -558,7 +554,7 @@ export const roadmapCommand: CommandSpec = {
558
554
  },
559
555
  mirror: {
560
556
  summary:
561
- "Build / debug close: append the feature row in the worktree, then the same row on dev under the dev lock (fail-open).",
557
+ "Build / debug close: append the feature row in the worktree, then land the same row on dev through a throwaway origin/dev checkout (fail-open).",
562
558
  flags: [
563
559
  { name: "workflow", type: "string", required: true, help: "build | debug" },
564
560
  { name: "fid", type: "string", required: true, help: "feature id (the row's key)" },
@@ -568,7 +564,7 @@ export const roadmapCommand: CommandSpec = {
568
564
  appended: "false when the worktree ledger could not be written",
569
565
  mirrored: "the row was committed and pushed on dev",
570
566
  skipped:
571
- "why the dev side was skipped: adopt mode | dev lock busy | dev checkout / pull failed | dev push failed (null when mirrored)",
567
+ "why the dev side was skipped: on dev | row not appended on dev | dev push refused | dev moved before each push | fetch of dev failed | throwaway checkout failed (null when mirrored)",
572
568
  },
573
569
  run: (ctx) => mirror(ctx),
574
570
  },
@@ -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,
@@ -106,8 +106,9 @@ export function classify(env: NodeJS.ProcessEnv, root: string, log: (m: string)
106
106
 
107
107
  /**
108
108
  * Default capabilities per runtime. CLOUD_CURSOR matches GITHUB_ACTION on
109
- * purpose (isolated VM, real git, mints and pushes its own branch); a claude.ai
110
- * session's proxy only lets it push the current branch, so it gets neither.
109
+ * purpose (isolated VM, real git, mints and pushes its own branch). A claude.ai
110
+ * session gets neither: whether it may push dev can't be tested without making
111
+ * that push, and a wrong guess strands the session on a dev checkout.
111
112
  */
112
113
  const capable = (runtime: Runtime) =>
113
114
  runtime === "LOCAL" || runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR";
@@ -19,6 +19,7 @@ import {
19
19
  import {
20
20
  CommandError,
21
21
  EXIT,
22
+ git,
22
23
  parseJson,
23
24
  statusLocation,
24
25
  type CommandSpec,
@@ -58,20 +59,43 @@ export const SUB_PLAN_FLAG: FlagSpec = {
58
59
  /** Exit code: status.jsonl missing, unreadable, or not valid NDJSON. */
59
60
  export const EXIT_NO_STATUS = 3;
60
61
 
61
- /** Parse every line of `status.jsonl`. Missing, unreadable or malformed is an error, never "no rows". */
62
62
  /** Every row of status.jsonl, whatever its type; exit 3 when the file is missing or a line is not JSON. */
63
63
  export function readStatusRows(file: string): StatusRow[] {
64
64
  if (!fs.existsSync(file)) throw new CommandError(EXIT_NO_STATUS, `${file} does not exist`);
65
- return fs
66
- .readFileSync(file, "utf-8")
65
+ return parseStatusRows(fs.readFileSync(file, "utf-8"), file);
66
+ }
67
+
68
+ /**
69
+ * The rows of status.jsonl as committed on `ref`, not as on disk: exit 3 when
70
+ * the ref does not carry the file. `file` need not exist; the repo is the one
71
+ * holding its nearest existing parent directory.
72
+ */
73
+ export function readStatusRowsAt(file: string, ref: string): StatusRow[] {
74
+ let dir = path.dirname(file);
75
+ while (!fs.existsSync(dir) && path.dirname(dir) !== dir) dir = path.dirname(dir);
76
+ const top = git(dir, ["rev-parse", "--show-toplevel"]);
77
+ if (top === null) throw new CommandError(EXIT_NO_STATUS, `${file} is not inside a git repo`);
78
+ const rel = path
79
+ .relative(fs.realpathSync(top), path.join(fs.realpathSync(dir), path.relative(dir, file)))
80
+ .split(path.sep)
81
+ .join("/");
82
+ const spec = `${ref}:${rel}`;
83
+ const text = git(top, ["show", spec]);
84
+ if (text === null) throw new CommandError(EXIT_NO_STATUS, `${spec} does not exist`);
85
+ return parseStatusRows(text, spec);
86
+ }
87
+
88
+ /** Parse NDJSON status text; `label` names it in errors. Malformed is an error, never "no rows". */
89
+ function parseStatusRows(text: string, label: string): StatusRow[] {
90
+ return text
67
91
  .split("\n")
68
92
  .map((l) => l.trim())
69
93
  .filter((l) => l !== "")
70
94
  .map((l, i) => {
71
95
  const parsed = parseJson(l);
72
- if (!parsed.ok) throw new CommandError(EXIT_NO_STATUS, `${file} line ${i + 1} is not JSON`);
96
+ if (!parsed.ok) throw new CommandError(EXIT_NO_STATUS, `${label} line ${i + 1} is not JSON`);
73
97
  if (typeof parsed.value !== "object" || parsed.value === null) {
74
- throw new CommandError(EXIT_NO_STATUS, `${file} line ${i + 1} is not a JSON object`);
98
+ throw new CommandError(EXIT_NO_STATUS, `${label} line ${i + 1} is not a JSON object`);
75
99
  }
76
100
  return parsed.value as StatusRow;
77
101
  });
@@ -83,6 +107,10 @@ export const readStatusEvents = (file: string): StatusEvent[] =>
83
107
 
84
108
  export const readRuns = (file: string): WorkflowRun[] => fold(readStatusEvents(file));
85
109
 
110
+ /** The runs as committed on `ref` (see readStatusRowsAt). */
111
+ export const readRunsAt = (file: string, ref: string): WorkflowRun[] =>
112
+ fold(readStatusRowsAt(file, ref) as StatusEvent[]);
113
+
86
114
  /** `--file`, resolved against the command's working directory. */
87
115
  export const statusFile = (ctx: RunContext) => path.resolve(ctx.cwd, String(ctx.flags.file));
88
116
 
@@ -242,11 +270,6 @@ export const statusCommand: CommandSpec = {
242
270
  WORKFLOW_FLAG,
243
271
  { name: "fid", type: "string", required: true, help: "feature id" },
244
272
  { name: "month", type: "string", required: true, help: "month bucket, YYYYMM" },
245
- {
246
- name: "dev-pushes",
247
- type: "boolean",
248
- help: "ship only: this runtime pushes to dev (RUNTIME_DEVPUSHES=true)",
249
- },
250
273
  ],
251
274
  output: {
252
275
  path: "absolute path to status.jsonl",
@@ -261,7 +284,6 @@ export const statusCommand: CommandSpec = {
261
284
  workflow: String(ctx.flags.workflow),
262
285
  fid: String(ctx.flags.fid),
263
286
  month,
264
- devPushes: ctx.flags.devPushes === true,
265
287
  });
266
288
  ctx.emit({ ...loc, exists: fs.existsSync(loc.path) });
267
289
  return EXIT.OK;
@@ -35,7 +35,7 @@ import {
35
35
  } from "../lib.js";
36
36
  import { FID_PATTERNS, readIssueTracker } from "./fids.js";
37
37
  import { buildComment } from "./issues.js";
38
- import { lockRoot, readHolder, resolveMonth, workflowLockPath } from "./locks.js";
38
+ import { readHolder, resolveMonth, workflowLockPath } from "./locks.js";
39
39
  import {
40
40
  EXIT_NO_STATUS,
41
41
  FILE_FLAG,
@@ -46,6 +46,7 @@ import {
46
46
  nonNegativeInt,
47
47
  positiveInt,
48
48
  readRuns,
49
+ readRunsAt,
49
50
  statusFile,
50
51
  str,
51
52
  } from "./status.js";
@@ -302,6 +303,7 @@ export const ROW_FIELDS: Record<string, readonly RowField[]> = {
302
303
  "build/build-summary": ["attempt"],
303
304
  "debug/debug-run-tests": ["attempt", "scope"],
304
305
  "debug/context-fetch": ["attempt"],
306
+ "debug/debug-failure-reproduce": ["attempt"],
305
307
  "debug/debug-failure-diagnose": ["attempt", "strategy"],
306
308
  "debug/debug-failure-remediate": ["attempt", "strategy"],
307
309
  "debug/debug-failure-soak": ["attempt"],
@@ -421,6 +423,8 @@ export interface Check {
421
423
 
422
424
  interface GateOptions {
423
425
  file?: string;
426
+ /** Read `file` as committed on this ref instead of from disk. */
427
+ ref?: string;
424
428
  workflow: string;
425
429
  step: string;
426
430
  subPlan?: number;
@@ -431,7 +435,6 @@ interface GateOptions {
431
435
  fid?: string;
432
436
  month?: string;
433
437
  token?: string;
434
- devPushes?: boolean;
435
438
  placeholders: string[];
436
439
  }
437
440
 
@@ -462,11 +465,8 @@ function gateChecks(cwd: string, o: GateOptions): Check[] {
462
465
  `${tracker} shape`,
463
466
  );
464
467
  if (o.token !== undefined) {
465
- const lock = workflowLockPath(
466
- lockRoot(cwd, o.workflow, o.devPushes === true),
467
- resolveMonth(repoRoot(cwd), o.fid, o.month),
468
- o.fid,
469
- );
468
+ const root = repoRoot(cwd);
469
+ const lock = workflowLockPath(root, resolveMonth(root, o.fid, o.month), o.fid);
470
470
  const holder = readHolder(lock);
471
471
  add(
472
472
  "workflow lock",
@@ -512,7 +512,8 @@ function gateChecks(cwd: string, o: GateOptions): Check[] {
512
512
  }
513
513
 
514
514
  if (o.file === undefined) return checks;
515
- const rows = activeDoneSteps(readRuns(o.file), o.workflow, { step: o.step, subPlan: o.subPlan });
515
+ const runs = o.ref === undefined ? readRuns(o.file) : readRunsAt(o.file, o.ref);
516
+ const rows = activeDoneSteps(runs, o.workflow, { step: o.step, subPlan: o.subPlan });
516
517
  const row = rows.filter((r) => o.attempt === undefined || r.attempt === o.attempt).at(-1);
517
518
  const rowProblems: string[] = [];
518
519
  if (!row) {
@@ -1186,6 +1187,11 @@ export const stepsCommand: CommandSpec = {
1186
1187
  required: false,
1187
1188
  help: "path to status.jsonl; without it the status row is not checked (Step 1)",
1188
1189
  },
1190
+ {
1191
+ name: "ref",
1192
+ type: "string",
1193
+ help: "read --file as committed on this ref (e.g. origin/dev), not from disk",
1194
+ },
1189
1195
  WORKFLOW_FLAG,
1190
1196
  STEP_FLAG,
1191
1197
  SUB_PLAN_FLAG,
@@ -1224,15 +1230,11 @@ export const stepsCommand: CommandSpec = {
1224
1230
  type: "string",
1225
1231
  help: "the workflow lock must be held with this token (needs --fid)",
1226
1232
  },
1227
- {
1228
- name: "dev-pushes",
1229
- type: "boolean",
1230
- help: "ship only: the lock lives in the main checkout",
1231
- },
1232
1233
  ],
1233
1234
  output: { pass: "true when every check passed", checks: "[{check, ok, detail}] per check" },
1234
1235
  exitCodes: {
1235
- [EXIT_NO_STATUS]: "status.jsonl missing, unreadable, or not valid NDJSON",
1236
+ [EXIT_NO_STATUS]:
1237
+ "status.jsonl missing (on disk, or on --ref), unreadable, or not valid NDJSON",
1236
1238
  },
1237
1239
  run: (ctx) => {
1238
1240
  const f = ctx.flags;
@@ -1243,12 +1245,21 @@ export const stepsCommand: CommandSpec = {
1243
1245
  throw new CommandError(EXIT.USAGE, "give --attempt or --attempt-of, not both");
1244
1246
  if (f.attemptOf !== undefined && file === undefined)
1245
1247
  throw new CommandError(EXIT.USAGE, "--attempt-of needs --file");
1248
+ const ref = str(f.ref);
1249
+ if (ref !== undefined && file === undefined)
1250
+ throw new CommandError(EXIT.USAGE, "--ref needs --file");
1251
+ if (ref !== undefined && f.attemptOf !== undefined)
1252
+ throw new CommandError(
1253
+ EXIT.USAGE,
1254
+ "--attempt-of reads the file on disk; give --attempt with --ref",
1255
+ );
1246
1256
  const attempt =
1247
1257
  f.attemptOf !== undefined
1248
1258
  ? derivedCounter(file!, workflow, String(f.attemptOf), subPlan, undefined)
1249
1259
  : nonNegativeInt(f.attempt, "attempt");
1250
1260
  const checks = gateChecks(ctx.cwd, {
1251
1261
  file,
1262
+ ref,
1252
1263
  workflow,
1253
1264
  step: String(f.step),
1254
1265
  subPlan,
@@ -1259,7 +1270,6 @@ export const stepsCommand: CommandSpec = {
1259
1270
  fid: str(f.fid),
1260
1271
  month: str(f.month),
1261
1272
  token: str(f.token),
1262
- devPushes: f.devPushes === true,
1263
1273
  placeholders: list(f.placeholder),
1264
1274
  });
1265
1275
  const pass = checks.every((c) => c.ok);
@@ -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;