@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
@@ -27,8 +27,19 @@ export const tipsIntro = (n: number) =>
27
27
  export const TIPS_DETAILS_POINTER =
28
28
  "Details for every tip: .bkit/advisories.md § Setup tips (refreshed by `bkit check`).";
29
29
 
30
+ /** Last line of a workflow's `## bkit Tips`: how to silence what it shows, by id. */
31
+ export function silenceLine(ids: readonly string[]): string {
32
+ const names = ids.map((id) => `\`${id}\``);
33
+ const list = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
34
+ const what = ids.length > 1 ? "these tips" : "this tip";
35
+ return `Want to silence ${what}? Ask your agent to "add ${list} to \`bkit.ignoreAdvisories\` in package.json".`;
36
+ }
37
+
30
38
  /** `bkit.ignoreAdvisories` key that silences `STAR_TIP`. */
31
- export const STAR_TIP_ID = "star";
39
+ export const STAR_TIP_ID = "bkit-star";
40
+
41
+ /** Older key that also silences `STAR_TIP`, so repos that set it keep the line off. */
42
+ export const STAR_TIP_OLD_ID = "star";
32
43
 
33
44
  /**
34
45
  * Last line of `bkit tips` output while not silenced, in bare `bkit tips` and the phase
@@ -59,7 +70,7 @@ export interface TipsResult {
59
70
  tips: SetupTip[];
60
71
  /** Firing tips the root `bkit.ignoreAdvisories` silenced. */
61
72
  suppressed: SuppressionNote[];
62
- /** False when the root `bkit.ignoreAdvisories` names `STAR_TIP_ID`. */
73
+ /** False when the root `bkit.ignoreAdvisories` names `STAR_TIP_ID` or `STAR_TIP_OLD_ID`. */
63
74
  star: boolean;
64
75
  }
65
76
 
@@ -73,7 +84,8 @@ export function collectTips(cwd: string, catalogue: readonly SetupTip[] = SETUP_
73
84
  if (isTipSilenced(tip, ignored)) suppressed.push({ id: tip.id, scope: "." });
74
85
  else tips.push(tip);
75
86
  }
76
- return { tips, suppressed, star: !ignored.has(STAR_TIP_ID) };
87
+ const star = !ignored.has(STAR_TIP_ID) && !ignored.has(STAR_TIP_OLD_ID);
88
+ return { tips, suppressed, star };
77
89
  }
78
90
 
79
91
  /**
@@ -106,11 +118,10 @@ function tipTextLines(tip: SetupTip, n: number): string[] {
106
118
  return lines;
107
119
  }
108
120
 
109
- /** One tip as markdown paragraphs for a workflow's `## bkit Tips` section. */
110
- function tipMarkdownLines(tip: SetupTip): string[] {
111
- const lines = [`**${tip.title}.** ${tip.line}`, "", `Ask your agent: "${tip.ask}"`];
112
- if (tip.caution) lines.push("", `Caution: ${tip.caution}`);
113
- return lines;
121
+ /** One tip as one markdown paragraph for a workflow's `## bkit Tips` section. */
122
+ function tipParagraph(tip: SetupTip): string {
123
+ const caution = tip.caution ? ` Caution: ${tip.caution}` : "";
124
+ return `**${tip.title}.** ${tip.line} Ask your agent: "${tip.ask}"${caution}`;
114
125
  }
115
126
 
116
127
  /**
@@ -128,45 +139,56 @@ export function starShownIn(workflow: TipsContext | null | undefined): boolean {
128
139
  }
129
140
 
130
141
  /**
131
- * `bkit tips` output, then where the rest live, then `STAR_TIP` when `star` is set and
132
- * `starShownIn(workflow)`. `""` when no tip fires and no star line shows.
133
- * - `workflow`: the `WORKFLOW_TIPS_CAP` tips that matter most in that workflow, as
134
- * markdown paragraphs with no intro or numbers — the workflow appends them under its
135
- * own `## bkit Tips` heading.
136
- * - neither: the top `TIPS_CAP` tips as a numbered terminal list.
142
+ * `bkit tips` output. `""` when no tip fires and no star line shows.
143
+ * - `workflow`: the `WORKFLOW_TIPS_CAP` tips that matter most in that workflow as
144
+ * one markdown paragraph each, then `STAR_TIP` when shown, then `silenceLine` naming both — the
145
+ * workflow appends them under its own `## bkit Tips` heading.
146
+ * - neither: the top `TIPS_CAP` tips as a numbered terminal list, where the rest live,
147
+ * then `STAR_TIP` when shown.
137
148
  * - `all`: every tip as a numbered list (in the workflow's order when `workflow` is set).
149
+ * `STAR_TIP` shows when `opts.star` is set and `starShownIn(workflow)`.
138
150
  */
139
151
  export function formatTips(
140
152
  tips: readonly SetupTip[],
141
153
  opts: { all?: boolean; workflow?: TipsContext | null; star?: boolean } = {},
142
154
  ): string {
155
+ const star = !!opts.star && starShownIn(opts.workflow);
156
+ if (opts.workflow && !opts.all) return formatWorkflowTips(tips, opts.workflow, star);
143
157
  const body = formatSetupTips(tips, opts);
144
- if (!opts.star || !starShownIn(opts.workflow)) return body;
158
+ if (!star) return body;
145
159
  return body ? `${body}\n\n${STAR_TIP}` : STAR_TIP;
146
160
  }
147
161
 
148
- /** `formatTips` without `STAR_TIP`. */
162
+ /** `formatTips` for a workflow's `## bkit Tips`: tips, star line, how to silence both. */
163
+ function formatWorkflowTips(
164
+ tips: readonly SetupTip[],
165
+ workflow: TipsContext,
166
+ star: boolean,
167
+ ): string {
168
+ const shown = orderForWorkflow(tips, workflow).slice(0, WORKFLOW_TIPS_CAP);
169
+ const ids = shown.map((t) => t.id);
170
+ const parts = shown.map(tipParagraph);
171
+ if (star) {
172
+ parts.push(STAR_TIP);
173
+ ids.push(STAR_TIP_ID);
174
+ }
175
+ if (ids.length === 0) return "";
176
+ return [...parts, silenceLine(ids)].join("\n\n");
177
+ }
178
+
179
+ /** `formatTips` as a terminal list, without `STAR_TIP`. */
149
180
  function formatSetupTips(
150
181
  tips: readonly SetupTip[],
151
182
  opts: { all?: boolean; workflow?: TipsContext | null },
152
183
  ): string {
153
184
  if (tips.length === 0) return "";
154
185
  const ordered = opts.workflow ? orderForWorkflow(tips, opts.workflow) : [...tips];
155
- const cap = opts.workflow ? WORKFLOW_TIPS_CAP : TIPS_CAP;
156
- const shown = opts.all ? ordered : ordered.slice(0, cap);
186
+ const shown = opts.all ? ordered : ordered.slice(0, TIPS_CAP);
157
187
  const rest = tips.length - shown.length;
158
- const more = rest > 0 ? `${rest} more: \`bkit tips --all\`. ` : "";
159
-
160
- if (opts.workflow && !opts.all) {
161
- const lines: string[] = [];
162
- for (const tip of shown) lines.push(...tipMarkdownLines(tip), "");
163
- lines.push(`${more}${TIPS_DETAILS_POINTER}`);
164
- return lines.join("\n");
165
- }
166
188
 
167
189
  const lines = [tipsIntro(shown.length), ""];
168
190
  shown.forEach((tip, i) => lines.push(...tipTextLines(tip, i + 1), ""));
169
- if (more) lines.push(more.trimEnd());
191
+ if (rest > 0) lines.push(`${rest} more: \`bkit tips --all\`.`);
170
192
  lines.push(TIPS_DETAILS_POINTER);
171
193
  return lines.join("\n");
172
194
  }
@@ -600,7 +600,10 @@ Usage:
600
600
  Upgrade everything installed (no module flags). Diffs old
601
601
  vs new templates; conflict list emitted to stderr. Use
602
602
  --auto-apply for CI (apply non-conflicting; exit non-zero
603
- on any conflict).
603
+ on any conflict). Only a whole file you edited since bkit
604
+ wrote it conflicts; rendered files (agents, commands,
605
+ skills, .bkit/*.md) are always re-rendered — bkit check
606
+ flags an edit to one.
604
607
  --to=<version> / --latest atomically BUMP @cbartens/bkit
605
608
  (pnpm add), then re-render + re-pin in one step — so a
606
609
  version bump can never drift from its rendered mirrors.
@@ -625,8 +628,8 @@ Usage:
625
628
  the tips that matter there first and prints one (each
626
629
  workflow runs this at its close; audit and utility do the
627
630
  same for audits and the ledger / roadmap updaters);
628
- --all lists every one. Ends with a star line ("star" in
629
- bkit.ignoreAdvisories silences it), except under
631
+ --all lists every one. Ends with a star line ("bkit-star"
632
+ in bkit.ignoreAdvisories silences it), except under
630
633
  --workflow=audit|utility. Local checks only. Exits 0.
631
634
  bkit status Read-only host/provider status. Reports current host+provider
632
635
  (sampled from .claude/, .cursor/, package.json, and the
@@ -669,7 +672,7 @@ Usage:
669
672
  (design|plan|build|debug|ship). Without it, prints the
670
673
  ledger-health line only. Read-only: exits 0.
671
674
  bkit analysis Cross-repo analysis — reports counts/rates/elapsed-time,
672
- #183 size↔outcome regression, dispatch-size threshold,
675
+ change-size vs outcome regression, dispatch-size threshold,
673
676
  counterSource trust labelling, per-rule compliance
674
677
  rate over kind:"compliance" rows, and the
675
678
  unjustified-deferral rate per (subagent, model)
@@ -732,9 +735,10 @@ Dependency updaters (copy an example and own it):
732
735
  Cross-cutting / modifiers:
733
736
  --tracker=<name> Wire issue tracker integration. Values: github, linear, none
734
737
  (default). Records bkit.issueTracker in package.json and substitutes
735
- tracker snippets into command mirrors. Switching is free (re-run with
736
- a new value); a switch removes the old tracker's MCP entry unless you
737
- edited it. Does NOT own AGENTS.md (which is tracker-agnostic).
738
+ tracker snippets into command mirrors. Re-renders every installed
739
+ host, and works alone (bkit install --tracker=github). Switching is
740
+ free; a switch removes the old linear MCP entry unless you edited it
741
+ (github always stays). Does NOT own AGENTS.md (tracker-agnostic).
738
742
 
739
743
  Install flags:
740
744
  --auto-revert On a Phase 3 blocker, automatically run uninstall and exit 1.
@@ -803,21 +807,23 @@ function commandsUsage(): string {
803
807
 
804
808
  /**
805
809
  * Validate the verb/module-flag combination before any dispatch
806
- * work runs. `install` requires >=1 module flag (bare install errors);
807
- * `check` / `upgrade` take NO module flags — they
808
- * operate on everything already installed, so a stray flag is a hard error
809
- * pointing at the no-flag form. Returns the error message to print, or `null`
810
+ * work runs. `install` requires >=1 module flag or `--tracker=` (which re-renders
811
+ * every installed host); a bare install errors. `check` / `upgrade` take NO module
812
+ * flags — they operate on everything already installed, so a stray flag is a hard
813
+ * error pointing at the no-flag form. Returns the error message to print, or `null`
810
814
  * when the combination is valid.
811
815
  */
812
816
  export function validateModuleFlagsForVerb(
813
817
  verb: Verb,
814
818
  moduleFlags: Set<ModuleFlag>,
819
+ tracker: IssueTracker | null = null,
815
820
  ): string | null {
816
- if (verb === "install" && moduleFlags.size === 0) {
821
+ if (verb === "install" && moduleFlags.size === 0 && tracker === null) {
817
822
  return (
818
823
  "[bkit] `bkit install` requires at least one module flag. Name what to install: " +
819
824
  "--claude, --cursor, --codex, --antigravity, --opencode=<provider> (plus opt-in " +
820
- `--auto=<${CLOUD_VARIANTS.join("|")}>). Run \`bkit help\` for usage.`
825
+ `--auto=<${CLOUD_VARIANTS.join("|")}>), or --tracker=<name> alone to switch the ` +
826
+ "tracker on what is installed. Run `bkit help` for usage."
821
827
  );
822
828
  }
823
829
  if ((verb === "check" || verb === "upgrade") && moduleFlags.size > 0) {
@@ -904,8 +910,9 @@ export async function main() {
904
910
  return;
905
911
  }
906
912
 
907
- // install requires >=1 module flag; check/upgrade take NONE (validateModuleFlagsForVerb).
908
- const moduleFlagsError = validateModuleFlagsForVerb(verb, moduleFlags);
913
+ // install requires >=1 module flag or --tracker=; check/upgrade take NONE
914
+ // (validateModuleFlagsForVerb).
915
+ const moduleFlagsError = validateModuleFlagsForVerb(verb, moduleFlags, tracker);
909
916
  if (moduleFlagsError) {
910
917
  console.error(moduleFlagsError);
911
918
  process.exit(1);
@@ -54,25 +54,25 @@ export interface Violation {
54
54
  // ---------------------------------------------------------------------------
55
55
 
56
56
  export interface GitAdapter {
57
- /** Returns the diff stat paths (one per line, POSIX) for parentSha..HEAD. */
58
- diffPaths(parentSha: string, cwd: string): string[];
59
- /** Returns the subject line of HEAD. */
60
- headSubject(cwd: string): string;
57
+ /** Returns the diff stat paths (one per line, POSIX) for parentSha..head (HEAD by default). */
58
+ diffPaths(parentSha: string, cwd: string, head?: string): string[];
59
+ /** Returns the subject line of head (HEAD by default). */
60
+ headSubject(cwd: string, head?: string): string;
61
61
  }
62
62
 
63
63
  /** SHA charset guard — only raw hex SHAs from the ledger are accepted. */
64
64
  const SHA_RE = /^[0-9a-f]{7,40}$/;
65
65
 
66
66
  export const realGitAdapter: GitAdapter = {
67
- diffPaths(parentSha: string, cwd: string): string[] {
68
- if (!SHA_RE.test(parentSha)) {
67
+ diffPaths(parentSha: string, cwd: string, head = "HEAD"): string[] {
68
+ if (!SHA_RE.test(parentSha) || (head !== "HEAD" && !SHA_RE.test(head))) {
69
69
  console.error(
70
- `[bkit-comply] diffPaths: parentSha "${parentSha}" does not match /^[0-9a-f]{7,40}$/ — skipping diff`,
70
+ `[bkit-comply] diffPaths: "${parentSha}..${head}" is not a sha range — skipping diff`,
71
71
  );
72
72
  return [];
73
73
  }
74
74
  try {
75
- const output = execFileSync("git", ["diff", "--name-only", `${parentSha}..HEAD`], {
75
+ const output = execFileSync("git", ["diff", "--name-only", `${parentSha}..${head}`], {
76
76
  cwd,
77
77
  env: gitEnv(),
78
78
  encoding: "utf8",
@@ -88,9 +88,10 @@ export const realGitAdapter: GitAdapter = {
88
88
  }
89
89
  },
90
90
 
91
- headSubject(cwd: string): string {
91
+ headSubject(cwd: string, head = "HEAD"): string {
92
+ if (head !== "HEAD" && !SHA_RE.test(head)) return "";
92
93
  try {
93
- return execFileSync("git", ["log", "-1", "--format=%s"], {
94
+ return execFileSync("git", ["log", "-1", "--format=%s", head], {
94
95
  cwd,
95
96
  env: gitEnv(),
96
97
  encoding: "utf8",
@@ -157,6 +158,8 @@ export function ruleSkipCiNotHead(headSubject: string, phase: string): Violation
157
158
  export interface GraderInput {
158
159
  /** Git SHA of the parent commit (design-start / plan-start / etc.). */
159
160
  parentSha: string;
161
+ /** The commit graded, when not HEAD: ship's squash. */
162
+ headSha?: string;
160
163
  /** Workflow phase: design | plan | build | debug | ship */
161
164
  phase: string;
162
165
  /** Working directory for git commands. Defaults to process.cwd(). */
@@ -173,8 +176,8 @@ export function runGrader(input: GraderInput): Violation[] {
173
176
  try {
174
177
  const cwd = input.cwd ?? process.cwd();
175
178
  const adapter = input.gitAdapter ?? realGitAdapter;
176
- const diffPaths = adapter.diffPaths(input.parentSha, cwd);
177
- const headSubject = adapter.headSubject(cwd);
179
+ const diffPaths = adapter.diffPaths(input.parentSha, cwd, input.headSha);
180
+ const headSubject = adapter.headSubject(cwd, input.headSha);
178
181
 
179
182
  const violations: Violation[] = [];
180
183
 
@@ -279,21 +282,27 @@ export function appendComplianceRows(rows: ComplianceRow[], statsPath: string):
279
282
 
280
283
  /**
281
284
  * Grade `phase` over HEAD~1..HEAD (HEAD alone in a one-commit repo) and append
282
- * its compliance rows to `<cwd>/.bkit/stats.jsonl`. Fail-open: any error is
283
- * logged and returns null, so a close never stops on the grader.
285
+ * its compliance rows to `<cwd>/.bkit/stats.jsonl`. With `squashSha` (ship's
286
+ * close, run in the feature worktree) the squash commit is graded instead —
287
+ * its subject and `squash~1..squash` — so the grade covers the whole feature
288
+ * as it reaches main, not the worktree's last commit. Fail-open: any
289
+ * error is logged and returns null, so a close never stops on the grader.
284
290
  */
285
291
  export function gradeCompliance(
286
292
  cwd: string,
287
293
  phase: string,
288
294
  log: (m: string) => void,
295
+ squashSha?: string,
289
296
  ): Violation[] | null {
290
297
  try {
291
- const parentSha = resolveGitSha("HEAD~1", cwd) || resolveGitSha("HEAD", cwd);
298
+ const squashParent = squashSha === undefined ? "" : resolveGitSha(`${squashSha}~1`, cwd);
299
+ const parentSha = squashParent || resolveGitSha("HEAD~1", cwd) || resolveGitSha("HEAD", cwd);
292
300
  if (!parentSha) {
293
301
  log("[bkit-comply] cannot resolve a parent SHA (no commits?) — skipping grade");
294
302
  return null;
295
303
  }
296
- const violations = runGrader({ parentSha, phase, cwd });
304
+ const headSha = squashParent ? squashSha : undefined;
305
+ const violations = runGrader({ parentSha, phase, cwd, ...(headSha ? { headSha } : {}) });
297
306
  const rows = buildComplianceRows({
298
307
  violations,
299
308
  phase,
@@ -228,14 +228,21 @@ export async function runInstall(
228
228
  else if (dryRun) console.log(`${LOG_PREFIX} Running in check (dry-run) mode`);
229
229
 
230
230
  // `bkit check` scopes drift detection to what is INSTALLED (detected by sentinel files),
231
- // not to a fixed full set. `install` keeps its explicit resolved set.
232
- const effectiveModules = verb === "check" ? detectInstalledModules(process.cwd()) : modules;
231
+ // not to a fixed full set. `install` keeps its explicit resolved set, plus every installed
232
+ // host when `--tracker=` is given: each host renders tracker-specific commands, agents and
233
+ // MCP entries, so a host left out would keep the old tracker's.
234
+ const effectiveModules =
235
+ verb === "check"
236
+ ? detectInstalledModules(process.cwd())
237
+ : tracker !== null
238
+ ? new Set<ModuleFlag>([...modules, ...detectInstalledModules(process.cwd())])
239
+ : modules;
233
240
 
234
241
  // RENDER-input provider resolution. `bkit check` takes no `--opencode=` flag, so the parsed
235
242
  // `opencodeProvider` is null on the check path; it falls back to the INSTALLED provider
236
243
  // (package.json `bkit.opencodeProvider`, else the opencode.json provider block). On install
237
- // `?? detect` never fires: opencode joins the module set only when `--opencode=<provider>`
238
- // was given. The PARSED `opencodeProvider` alone drives the persist-to-package.json logic
244
+ // `?? detect` fires only when opencode joins as an installed host under `--tracker=`; with
245
+ // `--opencode=<provider>` the flag wins. The PARSED `opencodeProvider` alone drives the persist-to-package.json logic
239
246
  // below (gated on `!dryRun` + a real flag). The tracker is resolved from package.json below,
240
247
  // so the tracker-dependent opencode mcp block renders the same way on check.
241
248
  const renderOpencodeProvider = opencodeProvider ?? detectOpencodeProvider(process.cwd());
@@ -0,0 +1,156 @@
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
+
9
+ import * as fs from "node:fs";
10
+ import * as path from "node:path";
11
+ import { CommandError, DEV, EXIT, git, runGit } from "./lib.js";
12
+ import { TIMEOUTS } from "../shared/timeouts.js";
13
+
14
+ const REMOTE = "origin";
15
+ const UPSTREAM = `${REMOTE}/${DEV}`;
16
+
17
+ /** dev moved before git sent anything: git compared the remote's dev and stopped. */
18
+ const MOVED_BEFORE = /\[rejected\][^\n]*\((?:fetch first|non-fast-forward)\)/;
19
+ /** dev moved while the push was in flight: the server's ref update lost the race. */
20
+ const MOVED_DURING =
21
+ /\[remote rejected\][^\n]*\((?:incorrect old value provided|cannot lock ref[^\n]*)\)/;
22
+ /** The server turned the push away: branch protection, a ruleset, an HTTP 403. */
23
+ const REFUSED = /\[remote rejected\]|returned error: 403|\bGH0\d\d\b/;
24
+
25
+ /** A dev push rejected only because dev moved: rebuild on the new dev, push again. */
26
+ export const devMoved = (stderr: string) => MOVED_BEFORE.test(stderr) || MOVED_DURING.test(stderr);
27
+
28
+ /** A dev push the server refused for a reason other than dev moving. */
29
+ export const devRefused = (stderr: string) => !devMoved(stderr) && REFUSED.test(stderr);
30
+
31
+ /**
32
+ * Milliseconds to wait before retry `retry` (1-based) of a landing: `startS`
33
+ * doubling per retry, capped at `capS`, then jittered down by up to half so two
34
+ * landings that collided once do not retry in step.
35
+ */
36
+ export function landBackoffMs(
37
+ retry: number,
38
+ random: () => number = Math.random,
39
+ startS: number = TIMEOUTS.LAND_BACKOFF_START_S,
40
+ capS: number = TIMEOUTS.LAND_BACKOFF_CAP_S,
41
+ ): number {
42
+ const s = Math.min(startS * 2 ** (retry - 1), capS);
43
+ return Math.round(s * 1000 * (0.5 + random() / 2));
44
+ }
45
+
46
+ export const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
47
+
48
+ /** A FID names one folder: no separators, no `..`. */
49
+ const SAFE_FID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
50
+
51
+ /** The throwaway checkout a landing is built in, beside the feature worktrees. */
52
+ export function landDir(root: string, fid: string): string {
53
+ if (!SAFE_FID.test(fid) || fid.includes(".."))
54
+ throw new CommandError(EXIT.USAGE, `--fid "${fid}" is not a feature id`);
55
+ return path.join(root, ".worktrees", `_land-${fid}`);
56
+ }
57
+
58
+ /**
59
+ * Remove a throwaway checkout. A landing killed inside `worktree add` leaves it
60
+ * locked ("initializing"), which a single `--force` and `prune` both skip, so it
61
+ * is unlocked first; a folder git no longer lists is the landing's own scratch.
62
+ */
63
+ export function dropLandTree(root: string, dir: string): void {
64
+ runGit(root, ["worktree", "unlock", dir]);
65
+ if (fs.existsSync(dir)) runGit(root, ["worktree", "remove", "--force", "--force", dir]);
66
+ runGit(root, ["worktree", "prune"]);
67
+ if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
68
+ }
69
+
70
+ /** `core.hooksPath` pointing nowhere, so no hook runs. */
71
+ const NO_HOOKS = process.platform === "win32" ? "NUL" : "/dev/null";
72
+
73
+ /**
74
+ * Run `fn` with git hooks off for every git child it starts: one more
75
+ * `GIT_CONFIG_*` entry (git >= 2.31) setting `core.hooksPath`, restored after.
76
+ */
77
+ export async function withoutHooks<T>(fn: () => T | Promise<T>): Promise<T> {
78
+ const saved = process.env.GIT_CONFIG_COUNT;
79
+ const n = Number(saved ?? 0) || 0;
80
+ const key = `GIT_CONFIG_KEY_${n}`;
81
+ const value = `GIT_CONFIG_VALUE_${n}`;
82
+ process.env.GIT_CONFIG_COUNT = String(n + 1);
83
+ process.env[key] = "core.hooksPath";
84
+ process.env[value] = NO_HOOKS;
85
+ try {
86
+ return await fn();
87
+ } finally {
88
+ if (saved === undefined) delete process.env.GIT_CONFIG_COUNT;
89
+ else process.env.GIT_CONFIG_COUNT = saved;
90
+ delete process.env[key];
91
+ delete process.env[value];
92
+ }
93
+ }
94
+
95
+ export type DevPush =
96
+ | { kind: "landed"; sha: string; attempts: number }
97
+ /** The server refused for a reason other than dev moving (branch protection, a ruleset, a 403). */
98
+ | { kind: "refused"; stderr: string }
99
+ /** The push failed without a server answer (network, credentials): nothing landed, no PR. */
100
+ | { kind: "push-failed"; stderr: string }
101
+ /** dev moved before every one of LAND_ATTEMPTS pushes. */
102
+ | { kind: "exhausted"; attempts: number }
103
+ | { kind: "fetch-failed"; stderr: string }
104
+ | { kind: "setup-failed"; stderr: string };
105
+
106
+ /**
107
+ * Land one commit on dev: per attempt, fetch dev, add `dir` detached at
108
+ * origin/dev, let `build` make the commit there, push `HEAD:dev` — git hooks
109
+ * off. `build` throwing stops the landing with that throw. A server refusal runs
110
+ * `refused` on the built commit first, when given. `dir` is removed on every path.
111
+ */
112
+ export async function pushToDev(o: {
113
+ root: string;
114
+ dir: string;
115
+ build: (dir: string, attempt: number) => void;
116
+ refused?: (dir: string, stderr: string) => Promise<void>;
117
+ log: (line: string) => void;
118
+ }): Promise<DevPush> {
119
+ o.log("git hooks skipped in the throwaway dev checkout — it lands bookkeeping only");
120
+ for (let attempt = 1; ; attempt++) {
121
+ let wait = 0;
122
+ dropLandTree(o.root, o.dir);
123
+ try {
124
+ const outcome = await withoutHooks(async (): Promise<DevPush | null> => {
125
+ const fetched = runGit(o.root, ["fetch", REMOTE, DEV]);
126
+ if (!fetched.ok) return { kind: "fetch-failed", stderr: fetched.stderr };
127
+ const added = runGit(o.root, ["worktree", "add", "--detach", o.dir, UPSTREAM]);
128
+ if (!added.ok) return { kind: "setup-failed", stderr: added.stderr };
129
+ o.build(o.dir, attempt);
130
+ const pushed = runGit(o.dir, ["push", REMOTE, `HEAD:${DEV}`]);
131
+ if (pushed.ok) {
132
+ return {
133
+ kind: "landed",
134
+ sha: git(o.dir, ["rev-parse", "HEAD"]) ?? "",
135
+ attempts: attempt,
136
+ };
137
+ }
138
+ if (devRefused(pushed.stderr)) {
139
+ await o.refused?.(o.dir, pushed.stderr);
140
+ return { kind: "refused", stderr: pushed.stderr };
141
+ }
142
+ if (!devMoved(pushed.stderr)) return { kind: "push-failed", stderr: pushed.stderr };
143
+ return null;
144
+ });
145
+ if (outcome !== null) return outcome;
146
+ if (attempt >= TIMEOUTS.LAND_ATTEMPTS) return { kind: "exhausted", attempts: attempt };
147
+ wait = landBackoffMs(attempt);
148
+ o.log(
149
+ `dev moved before push ${attempt} of ${TIMEOUTS.LAND_ATTEMPTS} — rebuilding on the new dev in ${(wait / 1000).toFixed(1)}s`,
150
+ );
151
+ } finally {
152
+ dropLandTree(o.root, o.dir);
153
+ }
154
+ await sleep(wait);
155
+ }
156
+ }
@@ -442,8 +442,13 @@ export function runGh(cwd: string, args: string[], input?: string): GhResult {
442
442
  };
443
443
  }
444
444
 
445
- /** gh cannot serve this call here: not installed, or exit 4 (not logged in). */
446
- export const ghUnavailable = (res: GhResult): boolean => res.missing || res.status === 4;
445
+ /**
446
+ * gh cannot serve this call here: not installed, exit 4 (not logged in), or an
447
+ * HTTP 403 — a token or proxy that may not use this API, where the GitHub MCP
448
+ * (its own credentials) can.
449
+ */
450
+ export const ghUnavailable = (res: GhResult): boolean =>
451
+ res.missing || res.status === 4 || (!res.ok && /\bHTTP 403\b/.test(res.stderr));
447
452
 
448
453
  /**
449
454
  * The main checkout's root, from any worktree. `--git-common-dir` points at the
@@ -476,22 +481,19 @@ export interface StatusLocation {
476
481
  *
477
482
  * - design / plan / build / debug: the feature worktree's copy when it exists
478
483
  * (`.worktrees/{fid}`), else the main checkout's.
479
- * - ship: the main checkout when this runtime pushes to dev, else the current
480
- * worktree's top (the branch being shipped). An unresolved runtime takes the
481
- * least-capable answer: current worktree.
484
+ * - ship: the current worktree's top — the tree ship works in (the feature
485
+ * worktree, or the adopted checkout), so asked from inside it.
482
486
  */
483
487
  export function statusLocation(opts: {
484
488
  cwd: string;
485
489
  workflow: string;
486
490
  fid: string;
487
491
  month: string;
488
- devPushes?: boolean;
489
492
  }): StatusLocation {
490
493
  const root = repoRoot(opts.cwd);
491
494
  const rel = statusRelPath(opts.month, opts.fid);
492
495
  if (opts.workflow === "ship") {
493
- const bookRoot =
494
- opts.devPushes === true ? root : (git(opts.cwd, ["rev-parse", "--show-toplevel"]) ?? root);
496
+ const bookRoot = git(opts.cwd, ["rev-parse", "--show-toplevel"]) ?? root;
495
497
  return { bookRoot, path: path.join(bookRoot, rel) };
496
498
  }
497
499
  const worktree = path.join(root, ".worktrees", opts.fid);
@@ -11,6 +11,7 @@ import { setupCommand } from "./setup/setup.js";
11
11
  import { branchesCommand } from "./workflow/branches.js";
12
12
  import { contextCommand } from "./workflow/context.js";
13
13
  import { countersCommand } from "./workflow/counters.js";
14
+ import { diskCommand } from "./workflow/disk.js";
14
15
  import { fidsCommand } from "./workflow/fids.js";
15
16
  import { issuesCommand } from "./workflow/issues.js";
16
17
  import { ledgersCommand } from "./workflow/ledgers.js";
@@ -39,6 +40,7 @@ export const COMMANDS: readonly CommandSpec[] = [
39
40
  locksCommand,
40
41
  workflowsCommand,
41
42
  worktreesCommand,
43
+ diskCommand,
42
44
  branchesCommand,
43
45
  skillsCommand,
44
46
  prsCommand,
@@ -2,11 +2,13 @@
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
 
8
9
  import type { TipsContext } from "../cli.js";
9
10
  import { collectTips, formatTips } from "../checks/tips/index.js";
11
+ import { formatNotes, readNotes } from "./workflow/disk.js";
10
12
 
11
13
  export function runTipsCommand(
12
14
  all: boolean,
@@ -14,6 +16,8 @@ export function runTipsCommand(
14
16
  cwd: string = process.cwd(),
15
17
  ): void {
16
18
  const { tips, star } = collectTips(cwd);
17
- const output = formatTips(tips, { all, workflow, star });
19
+ const output = [formatNotes(readNotes(cwd)), formatTips(tips, { all, workflow, star })]
20
+ .filter((part) => part !== "")
21
+ .join("\n\n");
18
22
  if (output) console.log(output);
19
23
  }