@cbartens/bkit 5.3.0 → 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 (128) hide show
  1. package/.bkit/README.md +3 -2
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +8 -2
  4. package/.bkit/core/.bkit/README.md +2 -1
  5. package/.bkit/core/.bkit/cloud.md +33 -33
  6. package/.bkit/core/.bkit/comparison.md +1 -1
  7. package/.bkit/core/.bkit/install.md +6 -5
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +4 -3
  10. package/.bkit/core/.bkit/prompts.md +4 -3
  11. package/.bkit/core/.bkit/providers.md +1 -1
  12. package/.bkit/core/.bkit/templates.md +35 -5
  13. package/.bkit/core/.bkit/trackers.md +7 -8
  14. package/.bkit/core/.bkit/workflows.md +106 -86
  15. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  16. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  17. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  23. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  25. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  26. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  28. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  29. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  30. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  32. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  34. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  36. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  37. package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
  38. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  39. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  40. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  43. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  44. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  47. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  48. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  49. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  50. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  51. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -0
  52. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  53. package/.bkit/core/engine/cli.ts +22 -15
  54. package/.bkit/core/engine/commands/comply.ts +25 -16
  55. package/.bkit/core/engine/commands/install/install.ts +11 -4
  56. package/.bkit/core/engine/commands/land.ts +156 -0
  57. package/.bkit/core/engine/commands/lib.ts +10 -8
  58. package/.bkit/core/engine/commands/registry.ts +2 -0
  59. package/.bkit/core/engine/commands/tips.ts +7 -3
  60. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  61. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  62. package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
  63. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  64. package/.bkit/core/engine/commands/workflow/prs.ts +11 -2
  65. package/.bkit/core/engine/commands/workflow/roadmap.ts +48 -53
  66. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  67. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  68. package/.bkit/core/engine/commands/workflow/steps.ts +24 -15
  69. package/.bkit/core/engine/commands/workflow/workflows.ts +433 -265
  70. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  71. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  72. package/.bkit/core/engine/install/modules/core.ts +15 -0
  73. package/.bkit/core/engine/install/placeholders.ts +13 -17
  74. package/.bkit/core/engine/shared/settings.ts +8 -0
  75. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  76. package/.bkit/core/prompts/bkit-audit-generate.md +47 -4
  77. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -1
  78. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -1
  79. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
  80. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -1
  81. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -1
  82. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +3 -3
  83. package/.bkit/core/workflows/bkit-auto.md +2 -2
  84. package/.bkit/core/workflows/bkit-build.md +7 -7
  85. package/.bkit/core/workflows/bkit-debug.md +11 -11
  86. package/.bkit/core/workflows/bkit-design.md +20 -11
  87. package/.bkit/core/workflows/bkit-plan.md +23 -13
  88. package/.bkit/core/workflows/bkit-ship.md +82 -93
  89. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  90. package/.bkit/shared/.claude/settings.json +1 -0
  91. package/.bkit/shared/docs/deployments.md +29 -25
  92. package/.bkit/shared/gitignore +1 -2
  93. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  94. package/.bkit/templates/.github/workflows/bkit-ci.yml +7 -2
  95. package/.bkit/templates/.husky/pre-commit +6 -0
  96. package/.bkit/templates/.husky/pre-push +7 -0
  97. package/.bkit/templates/.lintstagedrc.json +5 -1
  98. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  99. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  100. package/CHANGELOG.md +48 -0
  101. package/README.md +97 -96
  102. package/dist/checks/status-holes.js +0 -1
  103. package/dist/checks/tips/catalogue.js +14 -0
  104. package/dist/checks/tips/index.js +44 -28
  105. package/dist/cli.js +22 -16
  106. package/dist/commands/comply.js +20 -13
  107. package/dist/commands/install/install.js +10 -4
  108. package/dist/commands/land.js +129 -0
  109. package/dist/commands/lib.js +9 -6
  110. package/dist/commands/registry.js +2 -0
  111. package/dist/commands/tips.js +7 -3
  112. package/dist/commands/workflow/branches.js +300 -243
  113. package/dist/commands/workflow/disk.js +452 -0
  114. package/dist/commands/workflow/issues.js +63 -27
  115. package/dist/commands/workflow/locks.js +35 -130
  116. package/dist/commands/workflow/prs.js +5 -2
  117. package/dist/commands/workflow/roadmap.js +49 -56
  118. package/dist/commands/workflow/runtime.js +3 -2
  119. package/dist/commands/workflow/status.js +32 -12
  120. package/dist/commands/workflow/steps.js +18 -11
  121. package/dist/commands/workflow/workflows.js +388 -247
  122. package/dist/commands/workflow/workstreams.js +3 -2
  123. package/dist/commands/workflow/worktrees.js +11 -1
  124. package/dist/install/modules/core.js +13 -0
  125. package/dist/install/placeholders.js +13 -19
  126. package/dist/shared/settings.js +5 -0
  127. package/dist/shared/timeouts.js +8 -7
  128. package/package.json +1 -1
package/dist/cli.js CHANGED
@@ -443,7 +443,10 @@ Usage:
443
443
  Upgrade everything installed (no module flags). Diffs old
444
444
  vs new templates; conflict list emitted to stderr. Use
445
445
  --auto-apply for CI (apply non-conflicting; exit non-zero
446
- on any conflict).
446
+ on any conflict). Only a whole file you edited since bkit
447
+ wrote it conflicts; rendered files (agents, commands,
448
+ skills, .bkit/*.md) are always re-rendered — bkit check
449
+ flags an edit to one.
447
450
  --to=<version> / --latest atomically BUMP @cbartens/bkit
448
451
  (pnpm add), then re-render + re-pin in one step — so a
449
452
  version bump can never drift from its rendered mirrors.
@@ -468,8 +471,8 @@ Usage:
468
471
  the tips that matter there first and prints one (each
469
472
  workflow runs this at its close; audit and utility do the
470
473
  same for audits and the ledger / roadmap updaters);
471
- --all lists every one. Ends with a star line ("star" in
472
- bkit.ignoreAdvisories silences it), except under
474
+ --all lists every one. Ends with a star line ("bkit-star"
475
+ in bkit.ignoreAdvisories silences it), except under
473
476
  --workflow=audit|utility. Local checks only. Exits 0.
474
477
  bkit status Read-only host/provider status. Reports current host+provider
475
478
  (sampled from .claude/, .cursor/, package.json, and the
@@ -512,7 +515,7 @@ Usage:
512
515
  (design|plan|build|debug|ship). Without it, prints the
513
516
  ledger-health line only. Read-only: exits 0.
514
517
  bkit analysis Cross-repo analysis — reports counts/rates/elapsed-time,
515
- #183 size↔outcome regression, dispatch-size threshold,
518
+ change-size vs outcome regression, dispatch-size threshold,
516
519
  counterSource trust labelling, per-rule compliance
517
520
  rate over kind:"compliance" rows, and the
518
521
  unjustified-deferral rate per (subagent, model)
@@ -575,9 +578,10 @@ Dependency updaters (copy an example and own it):
575
578
  Cross-cutting / modifiers:
576
579
  --tracker=<name> Wire issue tracker integration. Values: github, linear, none
577
580
  (default). Records bkit.issueTracker in package.json and substitutes
578
- tracker snippets into command mirrors. Switching is free (re-run with
579
- a new value); a switch removes the old tracker's MCP entry unless you
580
- edited it. Does NOT own AGENTS.md (which is tracker-agnostic).
581
+ tracker snippets into command mirrors. Re-renders every installed
582
+ host, and works alone (bkit install --tracker=github). Switching is
583
+ free; a switch removes the old linear MCP entry unless you edited it
584
+ (github always stays). Does NOT own AGENTS.md (tracker-agnostic).
581
585
 
582
586
  Install flags:
583
587
  --auto-revert On a Phase 3 blocker, automatically run uninstall and exit 1.
@@ -644,17 +648,18 @@ function commandsUsage() {
644
648
  }
645
649
  /**
646
650
  * Validate the verb/module-flag combination before any dispatch
647
- * work runs. `install` requires >=1 module flag (bare install errors);
648
- * `check` / `upgrade` take NO module flags — they
649
- * operate on everything already installed, so a stray flag is a hard error
650
- * pointing at the no-flag form. Returns the error message to print, or `null`
651
+ * work runs. `install` requires >=1 module flag or `--tracker=` (which re-renders
652
+ * every installed host); a bare install errors. `check` / `upgrade` take NO module
653
+ * flags — they operate on everything already installed, so a stray flag is a hard
654
+ * error pointing at the no-flag form. Returns the error message to print, or `null`
651
655
  * when the combination is valid.
652
656
  */
653
- export function validateModuleFlagsForVerb(verb, moduleFlags) {
654
- if (verb === "install" && moduleFlags.size === 0) {
657
+ export function validateModuleFlagsForVerb(verb, moduleFlags, tracker = null) {
658
+ if (verb === "install" && moduleFlags.size === 0 && tracker === null) {
655
659
  return ("[bkit] `bkit install` requires at least one module flag. Name what to install: " +
656
660
  "--claude, --cursor, --codex, --antigravity, --opencode=<provider> (plus opt-in " +
657
- `--auto=<${CLOUD_VARIANTS.join("|")}>). Run \`bkit help\` for usage.`);
661
+ `--auto=<${CLOUD_VARIANTS.join("|")}>), or --tracker=<name> alone to switch the ` +
662
+ "tracker on what is installed. Run `bkit help` for usage.");
658
663
  }
659
664
  if ((verb === "check" || verb === "upgrade") && moduleFlags.size > 0) {
660
665
  return (`[bkit] \`bkit ${verb}\` takes no module flags — it operates on everything already ` +
@@ -714,8 +719,9 @@ export async function main() {
714
719
  await launchApp(verb, process.cwd());
715
720
  return;
716
721
  }
717
- // install requires >=1 module flag; check/upgrade take NONE (validateModuleFlagsForVerb).
718
- const moduleFlagsError = validateModuleFlagsForVerb(verb, moduleFlags);
722
+ // install requires >=1 module flag or --tracker=; check/upgrade take NONE
723
+ // (validateModuleFlagsForVerb).
724
+ const moduleFlagsError = validateModuleFlagsForVerb(verb, moduleFlags, tracker);
719
725
  if (moduleFlagsError) {
720
726
  console.error(moduleFlagsError);
721
727
  process.exit(1);
@@ -23,13 +23,13 @@ import { gitEnv, resolveGitSha, resolveRepoSlug, } from "../ledgers/telemetry.js
23
23
  /** SHA charset guard — only raw hex SHAs from the ledger are accepted. */
24
24
  const SHA_RE = /^[0-9a-f]{7,40}$/;
25
25
  export const realGitAdapter = {
26
- diffPaths(parentSha, cwd) {
27
- if (!SHA_RE.test(parentSha)) {
28
- console.error(`[bkit-comply] diffPaths: parentSha "${parentSha}" does not match /^[0-9a-f]{7,40}$/ — skipping diff`);
26
+ diffPaths(parentSha, cwd, head = "HEAD") {
27
+ if (!SHA_RE.test(parentSha) || (head !== "HEAD" && !SHA_RE.test(head))) {
28
+ console.error(`[bkit-comply] diffPaths: "${parentSha}..${head}" is not a sha range — skipping diff`);
29
29
  return [];
30
30
  }
31
31
  try {
32
- const output = execFileSync("git", ["diff", "--name-only", `${parentSha}..HEAD`], {
32
+ const output = execFileSync("git", ["diff", "--name-only", `${parentSha}..${head}`], {
33
33
  cwd,
34
34
  env: gitEnv(),
35
35
  encoding: "utf8",
@@ -45,9 +45,11 @@ export const realGitAdapter = {
45
45
  return [];
46
46
  }
47
47
  },
48
- headSubject(cwd) {
48
+ headSubject(cwd, head = "HEAD") {
49
+ if (head !== "HEAD" && !SHA_RE.test(head))
50
+ return "";
49
51
  try {
50
- return execFileSync("git", ["log", "-1", "--format=%s"], {
52
+ return execFileSync("git", ["log", "-1", "--format=%s", head], {
51
53
  cwd,
52
54
  env: gitEnv(),
53
55
  encoding: "utf8",
@@ -113,8 +115,8 @@ export function runGrader(input) {
113
115
  try {
114
116
  const cwd = input.cwd ?? process.cwd();
115
117
  const adapter = input.gitAdapter ?? realGitAdapter;
116
- const diffPaths = adapter.diffPaths(input.parentSha, cwd);
117
- const headSubject = adapter.headSubject(cwd);
118
+ const diffPaths = adapter.diffPaths(input.parentSha, cwd, input.headSha);
119
+ const headSubject = adapter.headSubject(cwd, input.headSha);
118
120
  const violations = [];
119
121
  const noMirrorViolation = ruleNoMirrorEdit(diffPaths);
120
122
  if (noMirrorViolation)
@@ -191,17 +193,22 @@ export function appendComplianceRows(rows, statsPath) {
191
193
  // ---------------------------------------------------------------------------
192
194
  /**
193
195
  * Grade `phase` over HEAD~1..HEAD (HEAD alone in a one-commit repo) and append
194
- * its compliance rows to `<cwd>/.bkit/stats.jsonl`. Fail-open: any error is
195
- * logged and returns null, so a close never stops on the grader.
196
+ * its compliance rows to `<cwd>/.bkit/stats.jsonl`. With `squashSha` (ship's
197
+ * close, run in the feature worktree) the squash commit is graded instead —
198
+ * its subject and `squash~1..squash` — so the grade covers the whole feature
199
+ * as it reaches main, not the worktree's last commit. Fail-open: any
200
+ * error is logged and returns null, so a close never stops on the grader.
196
201
  */
197
- export function gradeCompliance(cwd, phase, log) {
202
+ export function gradeCompliance(cwd, phase, log, squashSha) {
198
203
  try {
199
- const parentSha = resolveGitSha("HEAD~1", cwd) || resolveGitSha("HEAD", cwd);
204
+ const squashParent = squashSha === undefined ? "" : resolveGitSha(`${squashSha}~1`, cwd);
205
+ const parentSha = squashParent || resolveGitSha("HEAD~1", cwd) || resolveGitSha("HEAD", cwd);
200
206
  if (!parentSha) {
201
207
  log("[bkit-comply] cannot resolve a parent SHA (no commits?) — skipping grade");
202
208
  return null;
203
209
  }
204
- const violations = runGrader({ parentSha, phase, cwd });
210
+ const headSha = squashParent ? squashSha : undefined;
211
+ const violations = runGrader({ parentSha, phase, cwd, ...(headSha ? { headSha } : {}) });
205
212
  const rows = buildComplianceRows({
206
213
  violations,
207
214
  phase,
@@ -184,13 +184,19 @@ export async function runInstall(args, upgradeReport = false) {
184
184
  else if (dryRun)
185
185
  console.log(`${LOG_PREFIX} Running in check (dry-run) mode`);
186
186
  // `bkit check` scopes drift detection to what is INSTALLED (detected by sentinel files),
187
- // not to a fixed full set. `install` keeps its explicit resolved set.
188
- const effectiveModules = verb === "check" ? detectInstalledModules(process.cwd()) : modules;
187
+ // not to a fixed full set. `install` keeps its explicit resolved set, plus every installed
188
+ // host when `--tracker=` is given: each host renders tracker-specific commands, agents and
189
+ // MCP entries, so a host left out would keep the old tracker's.
190
+ const effectiveModules = verb === "check"
191
+ ? detectInstalledModules(process.cwd())
192
+ : tracker !== null
193
+ ? new Set([...modules, ...detectInstalledModules(process.cwd())])
194
+ : modules;
189
195
  // RENDER-input provider resolution. `bkit check` takes no `--opencode=` flag, so the parsed
190
196
  // `opencodeProvider` is null on the check path; it falls back to the INSTALLED provider
191
197
  // (package.json `bkit.opencodeProvider`, else the opencode.json provider block). On install
192
- // `?? detect` never fires: opencode joins the module set only when `--opencode=<provider>`
193
- // was given. The PARSED `opencodeProvider` alone drives the persist-to-package.json logic
198
+ // `?? detect` fires only when opencode joins as an installed host under `--tracker=`; with
199
+ // `--opencode=<provider>` the flag wins. The PARSED `opencodeProvider` alone drives the persist-to-package.json logic
194
200
  // below (gated on `!dryRun` + a real flag). The tracker is resolved from package.json below,
195
201
  // so the tracker-dependent opencode mcp block renders the same way on check.
196
202
  const renderOpencodeProvider = opencodeProvider ?? detectOpencodeProvider(process.cwd());
@@ -0,0 +1,129 @@
1
+ // The one way bkit lands a commit on dev: build it in a detached throwaway
2
+ // worktree off a fresh origin/dev and push it as dev. The main checkout's
3
+ // branch, index and edits are never touched, and local dev commits missing from
4
+ // origin/dev are never pushed. dev moved underneath → rebuild on the new dev and
5
+ // push again, with backoff. Used by the design / plan close, the build / debug
6
+ // roadmap mirror, and ship's close and FAILED record. The throwaway runs no git
7
+ // hooks: what it lands is bookkeeping only (docs, logs, ledgers, `[skip ci]`).
8
+ import * as fs from "node:fs";
9
+ import * as path from "node:path";
10
+ import { CommandError, DEV, EXIT, git, runGit } from "./lib.js";
11
+ import { TIMEOUTS } from "../shared/timeouts.js";
12
+ const REMOTE = "origin";
13
+ const UPSTREAM = `${REMOTE}/${DEV}`;
14
+ /** dev moved before git sent anything: git compared the remote's dev and stopped. */
15
+ const MOVED_BEFORE = /\[rejected\][^\n]*\((?:fetch first|non-fast-forward)\)/;
16
+ /** dev moved while the push was in flight: the server's ref update lost the race. */
17
+ const MOVED_DURING = /\[remote rejected\][^\n]*\((?:incorrect old value provided|cannot lock ref[^\n]*)\)/;
18
+ /** The server turned the push away: branch protection, a ruleset, an HTTP 403. */
19
+ const REFUSED = /\[remote rejected\]|returned error: 403|\bGH0\d\d\b/;
20
+ /** A dev push rejected only because dev moved: rebuild on the new dev, push again. */
21
+ export const devMoved = (stderr) => MOVED_BEFORE.test(stderr) || MOVED_DURING.test(stderr);
22
+ /** A dev push the server refused for a reason other than dev moving. */
23
+ export const devRefused = (stderr) => !devMoved(stderr) && REFUSED.test(stderr);
24
+ /**
25
+ * Milliseconds to wait before retry `retry` (1-based) of a landing: `startS`
26
+ * doubling per retry, capped at `capS`, then jittered down by up to half so two
27
+ * landings that collided once do not retry in step.
28
+ */
29
+ export function landBackoffMs(retry, random = Math.random, startS = TIMEOUTS.LAND_BACKOFF_START_S, capS = TIMEOUTS.LAND_BACKOFF_CAP_S) {
30
+ const s = Math.min(startS * 2 ** (retry - 1), capS);
31
+ return Math.round(s * 1000 * (0.5 + random() / 2));
32
+ }
33
+ export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
34
+ /** A FID names one folder: no separators, no `..`. */
35
+ const SAFE_FID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
36
+ /** The throwaway checkout a landing is built in, beside the feature worktrees. */
37
+ export function landDir(root, fid) {
38
+ if (!SAFE_FID.test(fid) || fid.includes(".."))
39
+ throw new CommandError(EXIT.USAGE, `--fid "${fid}" is not a feature id`);
40
+ return path.join(root, ".worktrees", `_land-${fid}`);
41
+ }
42
+ /**
43
+ * Remove a throwaway checkout. A landing killed inside `worktree add` leaves it
44
+ * locked ("initializing"), which a single `--force` and `prune` both skip, so it
45
+ * is unlocked first; a folder git no longer lists is the landing's own scratch.
46
+ */
47
+ export function dropLandTree(root, dir) {
48
+ runGit(root, ["worktree", "unlock", dir]);
49
+ if (fs.existsSync(dir))
50
+ runGit(root, ["worktree", "remove", "--force", "--force", dir]);
51
+ runGit(root, ["worktree", "prune"]);
52
+ if (fs.existsSync(dir))
53
+ fs.rmSync(dir, { recursive: true, force: true });
54
+ }
55
+ /** `core.hooksPath` pointing nowhere, so no hook runs. */
56
+ const NO_HOOKS = process.platform === "win32" ? "NUL" : "/dev/null";
57
+ /**
58
+ * Run `fn` with git hooks off for every git child it starts: one more
59
+ * `GIT_CONFIG_*` entry (git >= 2.31) setting `core.hooksPath`, restored after.
60
+ */
61
+ export async function withoutHooks(fn) {
62
+ const saved = process.env.GIT_CONFIG_COUNT;
63
+ const n = Number(saved ?? 0) || 0;
64
+ const key = `GIT_CONFIG_KEY_${n}`;
65
+ const value = `GIT_CONFIG_VALUE_${n}`;
66
+ process.env.GIT_CONFIG_COUNT = String(n + 1);
67
+ process.env[key] = "core.hooksPath";
68
+ process.env[value] = NO_HOOKS;
69
+ try {
70
+ return await fn();
71
+ }
72
+ finally {
73
+ if (saved === undefined)
74
+ delete process.env.GIT_CONFIG_COUNT;
75
+ else
76
+ process.env.GIT_CONFIG_COUNT = saved;
77
+ delete process.env[key];
78
+ delete process.env[value];
79
+ }
80
+ }
81
+ /**
82
+ * Land one commit on dev: per attempt, fetch dev, add `dir` detached at
83
+ * origin/dev, let `build` make the commit there, push `HEAD:dev` — git hooks
84
+ * off. `build` throwing stops the landing with that throw. A server refusal runs
85
+ * `refused` on the built commit first, when given. `dir` is removed on every path.
86
+ */
87
+ export async function pushToDev(o) {
88
+ o.log("git hooks skipped in the throwaway dev checkout — it lands bookkeeping only");
89
+ for (let attempt = 1;; attempt++) {
90
+ let wait = 0;
91
+ dropLandTree(o.root, o.dir);
92
+ try {
93
+ const outcome = await withoutHooks(async () => {
94
+ const fetched = runGit(o.root, ["fetch", REMOTE, DEV]);
95
+ if (!fetched.ok)
96
+ return { kind: "fetch-failed", stderr: fetched.stderr };
97
+ const added = runGit(o.root, ["worktree", "add", "--detach", o.dir, UPSTREAM]);
98
+ if (!added.ok)
99
+ return { kind: "setup-failed", stderr: added.stderr };
100
+ o.build(o.dir, attempt);
101
+ const pushed = runGit(o.dir, ["push", REMOTE, `HEAD:${DEV}`]);
102
+ if (pushed.ok) {
103
+ return {
104
+ kind: "landed",
105
+ sha: git(o.dir, ["rev-parse", "HEAD"]) ?? "",
106
+ attempts: attempt,
107
+ };
108
+ }
109
+ if (devRefused(pushed.stderr)) {
110
+ await o.refused?.(o.dir, pushed.stderr);
111
+ return { kind: "refused", stderr: pushed.stderr };
112
+ }
113
+ if (!devMoved(pushed.stderr))
114
+ return { kind: "push-failed", stderr: pushed.stderr };
115
+ return null;
116
+ });
117
+ if (outcome !== null)
118
+ return outcome;
119
+ if (attempt >= TIMEOUTS.LAND_ATTEMPTS)
120
+ return { kind: "exhausted", attempts: attempt };
121
+ wait = landBackoffMs(attempt);
122
+ o.log(`dev moved before push ${attempt} of ${TIMEOUTS.LAND_ATTEMPTS} — rebuilding on the new dev in ${(wait / 1000).toFixed(1)}s`);
123
+ }
124
+ finally {
125
+ dropLandTree(o.root, o.dir);
126
+ }
127
+ await sleep(wait);
128
+ }
129
+ }
@@ -327,8 +327,12 @@ export function runGh(cwd, args, input) {
327
327
  status: res.status,
328
328
  };
329
329
  }
330
- /** gh cannot serve this call here: not installed, or exit 4 (not logged in). */
331
- export const ghUnavailable = (res) => res.missing || res.status === 4;
330
+ /**
331
+ * gh cannot serve this call here: not installed, exit 4 (not logged in), or an
332
+ * HTTP 403 — a token or proxy that may not use this API, where the GitHub MCP
333
+ * (its own credentials) can.
334
+ */
335
+ export const ghUnavailable = (res) => res.missing || res.status === 4 || (!res.ok && /\bHTTP 403\b/.test(res.stderr));
332
336
  /**
333
337
  * The main checkout's root, from any worktree. `--git-common-dir` points at the
334
338
  * shared `.git`, so a linked worktree resolves to the same root as the main one.
@@ -350,15 +354,14 @@ export const statusRelPath = (month, fid) => path.join("docs", "plans", month, "
350
354
  *
351
355
  * - design / plan / build / debug: the feature worktree's copy when it exists
352
356
  * (`.worktrees/{fid}`), else the main checkout's.
353
- * - ship: the main checkout when this runtime pushes to dev, else the current
354
- * worktree's top (the branch being shipped). An unresolved runtime takes the
355
- * least-capable answer: current worktree.
357
+ * - ship: the current worktree's top — the tree ship works in (the feature
358
+ * worktree, or the adopted checkout), so asked from inside it.
356
359
  */
357
360
  export function statusLocation(opts) {
358
361
  const root = repoRoot(opts.cwd);
359
362
  const rel = statusRelPath(opts.month, opts.fid);
360
363
  if (opts.workflow === "ship") {
361
- const bookRoot = opts.devPushes === true ? root : (git(opts.cwd, ["rev-parse", "--show-toplevel"]) ?? root);
364
+ const bookRoot = git(opts.cwd, ["rev-parse", "--show-toplevel"]) ?? root;
362
365
  return { bookRoot, path: path.join(bookRoot, rel) };
363
366
  }
364
367
  const worktree = path.join(root, ".worktrees", opts.fid);
@@ -9,6 +9,7 @@ import { setupCommand } from "./setup/setup.js";
9
9
  import { branchesCommand } from "./workflow/branches.js";
10
10
  import { contextCommand } from "./workflow/context.js";
11
11
  import { countersCommand } from "./workflow/counters.js";
12
+ import { diskCommand } from "./workflow/disk.js";
12
13
  import { fidsCommand } from "./workflow/fids.js";
13
14
  import { issuesCommand } from "./workflow/issues.js";
14
15
  import { ledgersCommand } from "./workflow/ledgers.js";
@@ -36,6 +37,7 @@ export const COMMANDS = [
36
37
  locksCommand,
37
38
  workflowsCommand,
38
39
  worktreesCommand,
40
+ diskCommand,
39
41
  branchesCommand,
40
42
  skillsCommand,
41
43
  prsCommand,
@@ -2,12 +2,16 @@
2
2
  // apply to this repo. Each workflow passes its name at its close and gets the one tip that
3
3
  // matters most there (`audit` / `utility` for the audit agent and the ledger / roadmap
4
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
+ // output unless `bkit-star` is in `bkit.ignoreAdvisories`. Local checks only, no network; prints
6
+ // nothing when no tip fires and no star line shows; exits 0. What the last disk clean-up left
7
+ // for the person to decide (`bkit disk prune` notes) comes first, outside the tip cap.
7
8
  import { collectTips, formatTips } from "../checks/tips/index.js";
9
+ import { formatNotes, readNotes } from "./workflow/disk.js";
8
10
  export function runTipsCommand(all, workflow, cwd = process.cwd()) {
9
11
  const { tips, star } = collectTips(cwd);
10
- const output = formatTips(tips, { all, workflow, star });
12
+ const output = [formatNotes(readNotes(cwd)), formatTips(tips, { all, workflow, star })]
13
+ .filter((part) => part !== "")
14
+ .join("\n\n");
11
15
  if (output)
12
16
  console.log(output);
13
17
  }