@cbartens/bkit 5.3.0 → 5.5.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 (186) hide show
  1. package/.bkit/README.md +20 -7
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +14 -9
  4. package/.bkit/core/.bkit/README.md +19 -6
  5. package/.bkit/core/.bkit/cloud.md +77 -46
  6. package/.bkit/core/.bkit/comparison.md +3 -3
  7. package/.bkit/core/.bkit/install.md +21 -18
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +6 -3
  10. package/.bkit/core/.bkit/prompts.md +14 -10
  11. package/.bkit/core/.bkit/providers.md +7 -7
  12. package/.bkit/core/.bkit/templates.md +46 -10
  13. package/.bkit/core/.bkit/trackers.md +92 -38
  14. package/.bkit/core/.bkit/workflows.md +140 -116
  15. package/.bkit/core/AGENTS.md +2 -2
  16. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  17. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +2 -2
  23. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  25. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  26. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  28. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  30. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  31. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  33. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  35. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  36. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  38. package/.bkit/core/docs/templates/bkit-audit-issues.md +25 -8
  39. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  40. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  41. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  43. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  44. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  46. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  47. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  48. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  50. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  51. package/.bkit/core/engine/checks/after/auth.ts +88 -45
  52. package/.bkit/core/engine/checks/after/github.ts +18 -5
  53. package/.bkit/core/engine/checks/after/index.ts +1 -1
  54. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  55. package/.bkit/core/engine/checks/before/env.ts +28 -18
  56. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  57. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  58. package/.bkit/core/engine/checks/tips/catalogue.ts +31 -2
  59. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  60. package/.bkit/core/engine/cli.ts +27 -18
  61. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  62. package/.bkit/core/engine/commands/comply.ts +25 -16
  63. package/.bkit/core/engine/commands/install/install.ts +11 -4
  64. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  65. package/.bkit/core/engine/commands/land.ts +156 -0
  66. package/.bkit/core/engine/commands/lib.ts +10 -8
  67. package/.bkit/core/engine/commands/registry.ts +2 -0
  68. package/.bkit/core/engine/commands/tips.ts +7 -3
  69. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  70. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  71. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  72. package/.bkit/core/engine/commands/workflow/issues.ts +106 -42
  73. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  74. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  75. package/.bkit/core/engine/commands/workflow/prs.ts +14 -3
  76. package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
  77. package/.bkit/core/engine/commands/workflow/roadmap.ts +53 -54
  78. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  79. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  80. package/.bkit/core/engine/commands/workflow/steps.ts +26 -17
  81. package/.bkit/core/engine/commands/workflow/workflows.ts +442 -269
  82. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  83. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  84. package/.bkit/core/engine/install/manifest.ts +31 -10
  85. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  86. package/.bkit/core/engine/install/modules/core.ts +97 -4
  87. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  88. package/.bkit/core/engine/install/placeholders.ts +13 -17
  89. package/.bkit/core/engine/install/write.ts +37 -1
  90. package/.bkit/core/engine/render/trackers.ts +35 -23
  91. package/.bkit/core/engine/shared/egress.ts +6 -0
  92. package/.bkit/core/engine/shared/settings.ts +96 -1
  93. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  94. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  95. package/.bkit/core/prompts/bkit-audit-generate.md +80 -7
  96. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  97. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  98. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  99. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  100. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  101. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  102. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  103. package/.bkit/core/prompts/bkit-design-generate.md +2 -1
  104. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  105. package/.bkit/core/prompts/bkit-utility-update-decisions.md +4 -2
  106. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +4 -2
  107. package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
  108. package/.bkit/core/prompts/bkit-utility-update-failures.md +4 -2
  109. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +4 -2
  110. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +12 -5
  111. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  112. package/.bkit/core/workflows/bkit-auto.md +19 -6
  113. package/.bkit/core/workflows/bkit-build.md +64 -22
  114. package/.bkit/core/workflows/bkit-debug.md +72 -28
  115. package/.bkit/core/workflows/bkit-design.md +101 -37
  116. package/.bkit/core/workflows/bkit-plan.md +82 -31
  117. package/.bkit/core/workflows/bkit-ship.md +127 -108
  118. package/.bkit/shared/.bkit/.env.example +8 -0
  119. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  120. package/.bkit/shared/.claude/settings.json +4 -1
  121. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  122. package/.bkit/shared/.cursor/mcp.json +11 -4
  123. package/.bkit/shared/.mcp.json +11 -4
  124. package/.bkit/shared/.opencode/opencode.json +2 -0
  125. package/.bkit/shared/docs/deployments.md +44 -29
  126. package/.bkit/shared/docs/security.md +1 -1
  127. package/.bkit/shared/docs/testing.md +3 -3
  128. package/.bkit/shared/gitignore +1 -2
  129. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  130. package/.bkit/templates/.github/renovate.json5 +1 -1
  131. package/.bkit/templates/.github/workflows/bkit-ci.yml +29 -56
  132. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  133. package/.bkit/templates/.husky/pre-commit +10 -4
  134. package/.bkit/templates/.husky/pre-push +69 -12
  135. package/.bkit/templates/.lintstagedrc.json +5 -1
  136. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
  137. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
  138. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  139. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  140. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  141. package/CHANGELOG.md +85 -1
  142. package/README.md +102 -100
  143. package/dist/checks/after/auth.js +81 -45
  144. package/dist/checks/after/github.js +17 -5
  145. package/dist/checks/after/index.js +1 -1
  146. package/dist/checks/after/tools.js +1 -1
  147. package/dist/checks/before/env.js +24 -17
  148. package/dist/checks/before/mcp.js +4 -2
  149. package/dist/checks/status-holes.js +0 -1
  150. package/dist/checks/tips/catalogue.js +28 -2
  151. package/dist/checks/tips/index.js +44 -28
  152. package/dist/cli.js +27 -19
  153. package/dist/commands/ci/ci.js +100 -0
  154. package/dist/commands/comply.js +20 -13
  155. package/dist/commands/install/install.js +10 -4
  156. package/dist/commands/install/uninstall.js +42 -0
  157. package/dist/commands/land.js +129 -0
  158. package/dist/commands/lib.js +9 -6
  159. package/dist/commands/registry.js +2 -0
  160. package/dist/commands/tips.js +7 -3
  161. package/dist/commands/workflow/branches.js +300 -243
  162. package/dist/commands/workflow/disk.js +452 -0
  163. package/dist/commands/workflow/fids.js +22 -15
  164. package/dist/commands/workflow/issues.js +90 -41
  165. package/dist/commands/workflow/ledgers.js +26 -11
  166. package/dist/commands/workflow/locks.js +35 -130
  167. package/dist/commands/workflow/prs.js +8 -3
  168. package/dist/commands/workflow/repo.js +5 -0
  169. package/dist/commands/workflow/roadmap.js +52 -57
  170. package/dist/commands/workflow/runtime.js +3 -2
  171. package/dist/commands/workflow/status.js +32 -12
  172. package/dist/commands/workflow/steps.js +20 -13
  173. package/dist/commands/workflow/workflows.js +397 -251
  174. package/dist/commands/workflow/workstreams.js +3 -2
  175. package/dist/commands/workflow/worktrees.js +11 -1
  176. package/dist/install/manifest.js +30 -10
  177. package/dist/install/modules/cloud.js +3 -1
  178. package/dist/install/modules/core.js +95 -5
  179. package/dist/install/modules/opencode.js +6 -0
  180. package/dist/install/placeholders.js +13 -19
  181. package/dist/install/write.js +26 -2
  182. package/dist/render/trackers.js +34 -20
  183. package/dist/shared/egress.js +6 -0
  184. package/dist/shared/settings.js +44 -0
  185. package/dist/shared/timeouts.js +8 -7
  186. package/package.json +11 -2
@@ -11,6 +11,7 @@ import * as path from "node:path";
11
11
  import { parseRemoteUrlToSlug } from "../../ledgers/telemetry.js";
12
12
  import { DEV, EXIT, git, repoRoot, runGit, runTool } from "../lib.js";
13
13
  import { bkitVersionStatus } from "../../shared/bkit-latest.js";
14
+ import { readBkitConfig, trackerScope } from "../../shared/settings.js";
14
15
  /** Exit code: neither gh nor the origin remote named an owner/repo. */
15
16
  export const EXIT_NO_REPO = 3;
16
17
  /** Exit code: HEAD is detached, so there is no current branch (and --allow-detached was not given). */
@@ -112,6 +113,9 @@ export const repoCommand = {
112
113
  bkitLatest: "newest published @cbartens/bkit, asked at most once a day (null when offline, opted out via BKIT_NO_UPDATE_CHECK, or unpinned)",
113
114
  bkitOutdated: "true when bkitVersion is older than bkitLatest (null when either is unknown)",
114
115
  bkitAdvisory: "one line to show the user when bkitOutdated, else null",
116
+ trackerTeam: "package.json bkit.linear.team under linear, else null",
117
+ trackerProject: "package.json bkit.linear.project under linear, bkit.jira.project under jira, else null",
118
+ trackerSite: "package.json bkit.jira.site under jira (the MCP cloudId), else null",
115
119
  },
116
120
  exitCodes: {
117
121
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -157,6 +161,7 @@ export const repoCommand = {
157
161
  bkitLatest: latest.latest,
158
162
  bkitOutdated: latest.outdated,
159
163
  bkitAdvisory: latest.advisory,
164
+ ...trackerScope(readBkitConfig(root)),
160
165
  });
161
166
  if (branch === null && ctx.flags.allowDetached !== true) {
162
167
  ctx.log("HEAD is detached — no current branch");
@@ -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
@@ -19,7 +19,7 @@ import * as path from "node:path";
19
19
  import { compareTs, parse, resolveRepoSlug, validate } from "../../ledgers/telemetry.js";
20
20
  import { readBkitVersion } from "../../install/version-file.js";
21
21
  import { CommandError, DEV, EXIT, git, parseJson, repoRoot, runGit, } from "../lib.js";
22
- import { acquireDevLock, releaseLock } from "./locks.js";
22
+ import { landDir, pushToDev } from "../land.js";
23
23
  import { str } from "./status.js";
24
24
  /** Roadmap status each workflow's close moves the feature to. */
25
25
  export const FEATURE_STATUS = {
@@ -43,6 +43,8 @@ const ANALYSIS_PLACEHOLDER = "_(no analysis yet; run @bkit-utility-update-roadma
43
43
  const NOTES_PRE_PLACEHOLDER = "## Notes\n\n_(above the bkit list — yours, never overwritten)_";
44
44
  const NOTES_POST_PLACEHOLDER = "## Notes\n\n_(end of the board — yours, never overwritten)_";
45
45
  const BANNER = "> Generated tables — do not hand-edit the `bkit` tables; append to `.bkit/issues.jsonl` instead (an `ABANDONED` row hides a FID from every section). `## Notes` blocks are yours and are never overwritten. Everything above the first marker is also yours. notes-post is last. Analysis list length: `package.json` key `bkit.roadmapNext` (positive integer; absent or invalid → 25).";
46
+ /** Fixed related-utilities line; `@bkit-audit-generate` ends every run with the same text. */
47
+ export const RELATED_UTILITIES = "> Related utilities, run on demand: `@bkit-utility-update-roadmap` ranks the next best items in `docs/roadmap.md`; `@bkit-utility-update-tracker` brings tracker issues in line with the tracker rules; `@bkit-utility-update-deferrals` and `@bkit-utility-update-failures` close ledger rows the code already resolved; `@bkit-utility-update-decisions`, `@bkit-utility-update-knowledge` and `@bkit-utility-update-documentation` correct ledgers and docs the code has since contradicted.";
46
48
  /** Newest SHIPPED rows on the board; older ones stay in the ledger. */
47
49
  export const SHIPPED_ON_BOARD = 10;
48
50
  const SECTIONS = [
@@ -100,7 +102,7 @@ function table(rows) {
100
102
  ];
101
103
  }
102
104
  export function statusBlock(p, now) {
103
- const out = [BANNER, "", "## bkit", "", `_(refreshed ${now})_`];
105
+ const out = [BANNER, "", RELATED_UTILITIES, "", "## bkit", "", `_(refreshed ${now})_`];
104
106
  for (const [bucket, , heading] of SECTIONS)
105
107
  out.push("", heading, "", ...table(p[bucket]));
106
108
  return out.join("\n");
@@ -334,15 +336,13 @@ function feature(ctx) {
334
336
  ctx.emit({ ...r });
335
337
  return ctx.flags.strict === true && !r.appended ? EXIT.NO : EXIT.OK;
336
338
  }
337
- /** Seconds the mirror waits for a busy dev lock before skipping. */
338
- export const MIRROR_DEV_LOCK_DEADLINE_S = 60;
339
339
  const ROADMAP_FILES = [".bkit/issues.jsonl", "docs/roadmap.md"];
340
340
  /**
341
- * Build / debug close: append the feature row in the worktree, then copy the
342
- * SAME row to `dev` in the main checkout under the dev lock — checkout dev,
343
- * fast-forward, append, commit the two roadmap files, push, return to the prior
344
- * branch. Skipped in adopt mode (the worktree IS the main checkout) and when the
345
- * dev lock stays busy. Fail-open throughout: the feat-side row is already written.
341
+ * Build / debug close: append the feature row in the worktree, then land the
342
+ * SAME row on `dev` through a throwaway origin/dev checkout (`pushToDev`). The
343
+ * main checkout is never touched. Skipped when the run's own checkout is on dev
344
+ * (the row rides that branch's commit). Fail-open throughout: the feat-side row
345
+ * is already written and reaches dev with ship's merge.
346
346
  */
347
347
  async function mirror(ctx) {
348
348
  const workflow = String(ctx.flags.workflow);
@@ -356,51 +356,46 @@ async function mirror(ctx) {
356
356
  ctx.emit({ row: feat.row, appended: feat.appended, mirrored, skipped });
357
357
  return EXIT.OK;
358
358
  };
359
- if (path.resolve(wt) === path.resolve(root))
360
- return done(false, "adopt mode");
361
- let lock;
362
- try {
363
- lock = await acquireDevLock({
364
- cwd: root,
365
- workflow,
366
- fid,
367
- deadlineS: MIRROR_DEV_LOCK_DEADLINE_S,
368
- log: ctx.log,
369
- });
370
- }
371
- catch (err) {
372
- // A busy lock skips the mirror; it never fails the close.
373
- return done(false, `dev lock busy: ${err.message}`);
374
- }
375
- try {
376
- const prior = git(root, ["branch", "--show-current"]) ?? "";
377
- if (!runGit(root, ["checkout", DEV]).ok ||
378
- !runGit(root, ["pull", "--ff-only", "origin", DEV]).ok) {
379
- if (prior)
380
- runGit(root, ["checkout", prior]);
381
- return done(false, "dev checkout / pull failed");
382
- }
383
- const onDev = appendFeature(root, { row: JSON.stringify(feat.row) }, ctx.log);
384
- if (!onDev.appended)
385
- ctx.log("roadmap row skipped on dev");
386
- runGit(root, ["add", "--", ...ROADMAP_FILES]);
387
- runGit(root, [
388
- "commit",
389
- "--allow-empty",
390
- "-m",
391
- `docs(${fid}): ${workflow} roadmap update bkit [skip ci]`,
392
- "--",
393
- ...ROADMAP_FILES,
394
- ]);
395
- const pushed = runGit(root, ["push", "origin", DEV]).ok;
396
- if (!pushed)
397
- ctx.log("dev push failed — feat-side row already written");
398
- if (prior)
399
- runGit(root, ["checkout", prior]);
400
- return done(pushed, pushed ? null : "dev push failed");
401
- }
402
- finally {
403
- releaseLock(lock.path, { workflow, fid, token: lock.token });
359
+ if (git(wt, ["branch", "--show-current"]) === DEV)
360
+ return done(false, "on dev");
361
+ // A build that commits nothing pushes origin/dev back to itself, which git
362
+ // reports as success — so a landing counts only when this attempt committed.
363
+ let committed = "";
364
+ const res = await pushToDev({
365
+ root,
366
+ dir: landDir(root, fid),
367
+ build: (dir) => {
368
+ committed = "";
369
+ if (!appendFeature(dir, { row: JSON.stringify(feat.row) }, ctx.log).appended) {
370
+ committed = "row not appended on dev";
371
+ return;
372
+ }
373
+ runGit(dir, ["add", "--", ...ROADMAP_FILES]);
374
+ const made = runGit(dir, [
375
+ "commit",
376
+ "-m",
377
+ `docs(${fid}): ${workflow} roadmap update bkit [skip ci]`,
378
+ "--",
379
+ ...ROADMAP_FILES,
380
+ ]);
381
+ if (!made.ok)
382
+ committed = `roadmap commit failed: ${made.stderr || made.stdout}`;
383
+ },
384
+ log: ctx.log,
385
+ });
386
+ switch (res.kind) {
387
+ case "landed":
388
+ return committed ? done(false, committed) : done(true, null);
389
+ case "refused":
390
+ return done(false, `dev push refused: ${res.stderr}`);
391
+ case "push-failed":
392
+ return done(false, `dev push failed: ${res.stderr}`);
393
+ case "exhausted":
394
+ return done(false, `dev moved before each of ${res.attempts} pushes`);
395
+ case "fetch-failed":
396
+ return done(false, `fetch of dev failed: ${res.stderr}`);
397
+ case "setup-failed":
398
+ return done(false, `throwaway checkout failed: ${res.stderr}`);
404
399
  }
405
400
  }
406
401
  function writeBoard(md, board) {
@@ -478,7 +473,7 @@ export const roadmapCommand = {
478
473
  run: (ctx) => feature(ctx),
479
474
  },
480
475
  mirror: {
481
- summary: "Build / debug close: append the feature row in the worktree, then the same row on dev under the dev lock (fail-open).",
476
+ summary: "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).",
482
477
  flags: [
483
478
  { name: "workflow", type: "string", required: true, help: "build | debug" },
484
479
  { name: "fid", type: "string", required: true, help: "feature id (the row's key)" },
@@ -487,7 +482,7 @@ export const roadmapCommand = {
487
482
  row: "the row appended (worktree and dev)",
488
483
  appended: "false when the worktree ledger could not be written",
489
484
  mirrored: "the row was committed and pushed on dev",
490
- skipped: "why the dev side was skipped: adopt mode | dev lock busy | dev checkout / pull failed | dev push failed (null when mirrored)",
485
+ skipped: "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)",
491
486
  },
492
487
  run: (ctx) => mirror(ctx),
493
488
  },
@@ -81,8 +81,9 @@ export function classify(env, root, log) {
81
81
  }
82
82
  /**
83
83
  * Default capabilities per runtime. CLOUD_CURSOR matches GITHUB_ACTION on
84
- * purpose (isolated VM, real git, mints and pushes its own branch); a claude.ai
85
- * session's proxy only lets it push the current branch, so it gets neither.
84
+ * purpose (isolated VM, real git, mints and pushes its own branch). A claude.ai
85
+ * session gets neither: whether it may push dev can't be tested without making
86
+ * that push, and a wrong guess strands the session on a dev checkout.
86
87
  */
87
88
  const capable = (runtime) => runtime === "LOCAL" || runtime === "GITHUB_ACTION" || runtime === "CLOUD_CURSOR";
88
89
  /** No human can reply into the session: a GitHub Actions run. */
@@ -2,7 +2,7 @@
2
2
  import * as fs from "node:fs";
3
3
  import * as path from "node:path";
4
4
  import { activeDoneSteps, appendLine, fold, lastDoneStepAllRuns, lastRun, nextStrategy, runOrStepField, statusTimestamp, } from "../../ledgers/status.js";
5
- import { CommandError, EXIT, parseJson, statusLocation, } from "../lib.js";
5
+ import { CommandError, EXIT, git, parseJson, statusLocation, } from "../lib.js";
6
6
  // ---------------------------------------------------------------------------
7
7
  // Shared with counters / steps
8
8
  // ---------------------------------------------------------------------------
@@ -31,22 +31,46 @@ export const SUB_PLAN_FLAG = {
31
31
  };
32
32
  /** Exit code: status.jsonl missing, unreadable, or not valid NDJSON. */
33
33
  export const EXIT_NO_STATUS = 3;
34
- /** Parse every line of `status.jsonl`. Missing, unreadable or malformed is an error, never "no rows". */
35
34
  /** Every row of status.jsonl, whatever its type; exit 3 when the file is missing or a line is not JSON. */
36
35
  export function readStatusRows(file) {
37
36
  if (!fs.existsSync(file))
38
37
  throw new CommandError(EXIT_NO_STATUS, `${file} does not exist`);
39
- return fs
40
- .readFileSync(file, "utf-8")
38
+ return parseStatusRows(fs.readFileSync(file, "utf-8"), file);
39
+ }
40
+ /**
41
+ * The rows of status.jsonl as committed on `ref`, not as on disk: exit 3 when
42
+ * the ref does not carry the file. `file` need not exist; the repo is the one
43
+ * holding its nearest existing parent directory.
44
+ */
45
+ export function readStatusRowsAt(file, ref) {
46
+ let dir = path.dirname(file);
47
+ while (!fs.existsSync(dir) && path.dirname(dir) !== dir)
48
+ dir = path.dirname(dir);
49
+ const top = git(dir, ["rev-parse", "--show-toplevel"]);
50
+ if (top === null)
51
+ throw new CommandError(EXIT_NO_STATUS, `${file} is not inside a git repo`);
52
+ const rel = path
53
+ .relative(fs.realpathSync(top), path.join(fs.realpathSync(dir), path.relative(dir, file)))
54
+ .split(path.sep)
55
+ .join("/");
56
+ const spec = `${ref}:${rel}`;
57
+ const text = git(top, ["show", spec]);
58
+ if (text === null)
59
+ throw new CommandError(EXIT_NO_STATUS, `${spec} does not exist`);
60
+ return parseStatusRows(text, spec);
61
+ }
62
+ /** Parse NDJSON status text; `label` names it in errors. Malformed is an error, never "no rows". */
63
+ function parseStatusRows(text, label) {
64
+ return text
41
65
  .split("\n")
42
66
  .map((l) => l.trim())
43
67
  .filter((l) => l !== "")
44
68
  .map((l, i) => {
45
69
  const parsed = parseJson(l);
46
70
  if (!parsed.ok)
47
- throw new CommandError(EXIT_NO_STATUS, `${file} line ${i + 1} is not JSON`);
71
+ throw new CommandError(EXIT_NO_STATUS, `${label} line ${i + 1} is not JSON`);
48
72
  if (typeof parsed.value !== "object" || parsed.value === null) {
49
- throw new CommandError(EXIT_NO_STATUS, `${file} line ${i + 1} is not a JSON object`);
73
+ throw new CommandError(EXIT_NO_STATUS, `${label} line ${i + 1} is not a JSON object`);
50
74
  }
51
75
  return parsed.value;
52
76
  });
@@ -54,6 +78,8 @@ export function readStatusRows(file) {
54
78
  /** The rows as the fold reads them; the fold skips types it does not model. */
55
79
  export const readStatusEvents = (file) => readStatusRows(file);
56
80
  export const readRuns = (file) => fold(readStatusEvents(file));
81
+ /** The runs as committed on `ref` (see readStatusRowsAt). */
82
+ export const readRunsAt = (file, ref) => fold(readStatusRowsAt(file, ref));
57
83
  /** `--file`, resolved against the command's working directory. */
58
84
  export const statusFile = (ctx) => path.resolve(ctx.cwd, String(ctx.flags.file));
59
85
  /** `--field key=value`: value parsed as JSON when it parses, else kept as a string. */
@@ -197,11 +223,6 @@ export const statusCommand = {
197
223
  WORKFLOW_FLAG,
198
224
  { name: "fid", type: "string", required: true, help: "feature id" },
199
225
  { name: "month", type: "string", required: true, help: "month bucket, YYYYMM" },
200
- {
201
- name: "dev-pushes",
202
- type: "boolean",
203
- help: "ship only: this runtime pushes to dev (RUNTIME_DEVPUSHES=true)",
204
- },
205
226
  ],
206
227
  output: {
207
228
  path: "absolute path to status.jsonl",
@@ -217,7 +238,6 @@ export const statusCommand = {
217
238
  workflow: String(ctx.flags.workflow),
218
239
  fid: String(ctx.flags.fid),
219
240
  month,
220
- devPushes: ctx.flags.devPushes === true,
221
241
  });
222
242
  ctx.emit({ ...loc, exists: fs.existsSync(loc.path) });
223
243
  return EXIT.OK;
@@ -16,10 +16,10 @@ import { clampLogPath, readRecords } from "../../ledgers/clamp-log.js";
16
16
  import { resolveRepoSlug } from "../../ledgers/telemetry.js";
17
17
  import { getPromptsRoot } from "../../shared/package-roots.js";
18
18
  import { CommandError, EXIT, repoRoot, runGit, } from "../lib.js";
19
- import { FID_PATTERNS, readIssueTracker } from "./fids.js";
19
+ import { FID_PATTERNS, normaliseFid, readIssueTracker } from "./fids.js";
20
20
  import { buildComment } from "./issues.js";
21
- import { lockRoot, readHolder, resolveMonth, workflowLockPath } from "./locks.js";
22
- import { EXIT_NO_STATUS, FILE_FLAG, STEP_FLAG, SUB_PLAN_FLAG, WORKFLOW_FLAG, extraField, nonNegativeInt, positiveInt, readRuns, statusFile, str, } from "./status.js";
21
+ import { readHolder, resolveMonth, workflowLockPath } from "./locks.js";
22
+ import { EXIT_NO_STATUS, FILE_FLAG, STEP_FLAG, SUB_PLAN_FLAG, WORKFLOW_FLAG, extraField, nonNegativeInt, positiveInt, readRuns, readRunsAt, statusFile, str, } from "./status.js";
23
23
  const VERDICT_END = "<!-- verdict:end -->";
24
24
  const DEFAULT_VERDICTS = ["PASS", "CONCERNS", "FAIL"];
25
25
  const STRATEGIES = ["STANDARD", "PIVOT", "FINAL"];
@@ -324,12 +324,13 @@ function gateChecks(cwd, o) {
324
324
  }
325
325
  if (o.fid !== undefined) {
326
326
  const tracker = readIssueTracker(cwd);
327
- const fid = tracker === "linear" ? o.fid.toLowerCase() : o.fid;
327
+ const fid = normaliseFid(o.fid, tracker);
328
328
  add(`fid ${fid}`, FID_PATTERNS[tracker].test(fid)
329
329
  ? undefined
330
330
  : `does not match the ${tracker} shape ${FID_PATTERNS[tracker].source}`, `${tracker} shape`);
331
331
  if (o.token !== undefined) {
332
- const lock = workflowLockPath(lockRoot(cwd, o.workflow, o.devPushes === true), resolveMonth(repoRoot(cwd), o.fid, o.month), o.fid);
332
+ const root = repoRoot(cwd);
333
+ const lock = workflowLockPath(root, resolveMonth(root, o.fid, o.month), o.fid);
333
334
  const holder = readHolder(lock);
334
335
  add("workflow lock", holder === undefined
335
336
  ? `no lock at ${lock}`
@@ -365,7 +366,8 @@ function gateChecks(cwd, o) {
365
366
  }
366
367
  if (o.file === undefined)
367
368
  return checks;
368
- const rows = activeDoneSteps(readRuns(o.file), o.workflow, { step: o.step, subPlan: o.subPlan });
369
+ const runs = o.ref === undefined ? readRuns(o.file) : readRunsAt(o.file, o.ref);
370
+ const rows = activeDoneSteps(runs, o.workflow, { step: o.step, subPlan: o.subPlan });
369
371
  const row = rows.filter((r) => o.attempt === undefined || r.attempt === o.attempt).at(-1);
370
372
  const rowProblems = [];
371
373
  if (!row) {
@@ -981,6 +983,11 @@ export const stepsCommand = {
981
983
  required: false,
982
984
  help: "path to status.jsonl; without it the status row is not checked (Step 1)",
983
985
  },
986
+ {
987
+ name: "ref",
988
+ type: "string",
989
+ help: "read --file as committed on this ref (e.g. origin/dev), not from disk",
990
+ },
984
991
  WORKFLOW_FLAG,
985
992
  STEP_FLAG,
986
993
  SUB_PLAN_FLAG,
@@ -1019,15 +1026,10 @@ export const stepsCommand = {
1019
1026
  type: "string",
1020
1027
  help: "the workflow lock must be held with this token (needs --fid)",
1021
1028
  },
1022
- {
1023
- name: "dev-pushes",
1024
- type: "boolean",
1025
- help: "ship only: the lock lives in the main checkout",
1026
- },
1027
1029
  ],
1028
1030
  output: { pass: "true when every check passed", checks: "[{check, ok, detail}] per check" },
1029
1031
  exitCodes: {
1030
- [EXIT_NO_STATUS]: "status.jsonl missing, unreadable, or not valid NDJSON",
1032
+ [EXIT_NO_STATUS]: "status.jsonl missing (on disk, or on --ref), unreadable, or not valid NDJSON",
1031
1033
  },
1032
1034
  run: (ctx) => {
1033
1035
  const f = ctx.flags;
@@ -1038,11 +1040,17 @@ export const stepsCommand = {
1038
1040
  throw new CommandError(EXIT.USAGE, "give --attempt or --attempt-of, not both");
1039
1041
  if (f.attemptOf !== undefined && file === undefined)
1040
1042
  throw new CommandError(EXIT.USAGE, "--attempt-of needs --file");
1043
+ const ref = str(f.ref);
1044
+ if (ref !== undefined && file === undefined)
1045
+ throw new CommandError(EXIT.USAGE, "--ref needs --file");
1046
+ if (ref !== undefined && f.attemptOf !== undefined)
1047
+ throw new CommandError(EXIT.USAGE, "--attempt-of reads the file on disk; give --attempt with --ref");
1041
1048
  const attempt = f.attemptOf !== undefined
1042
1049
  ? derivedCounter(file, workflow, String(f.attemptOf), subPlan, undefined)
1043
1050
  : nonNegativeInt(f.attempt, "attempt");
1044
1051
  const checks = gateChecks(ctx.cwd, {
1045
1052
  file,
1053
+ ref,
1046
1054
  workflow,
1047
1055
  step: String(f.step),
1048
1056
  subPlan,
@@ -1053,7 +1061,6 @@ export const stepsCommand = {
1053
1061
  fid: str(f.fid),
1054
1062
  month: str(f.month),
1055
1063
  token: str(f.token),
1056
- devPushes: f.devPushes === true,
1057
1064
  placeholders: list(f.placeholder),
1058
1065
  });
1059
1066
  const pass = checks.every((c) => c.ok);