@cbartens/bkit 5.1.0 → 5.2.1

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 (193) hide show
  1. package/.bkit/README.md +11 -7
  2. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +39 -50
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +74 -56
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
  5. package/.bkit/core/.agents/rules.md +8 -4
  6. package/.bkit/core/.agents/shortcuts.md +1 -1
  7. package/.bkit/core/.bkit/LICENSE.md +18 -140
  8. package/.bkit/core/.bkit/README.md +10 -6
  9. package/.bkit/core/.bkit/cloud.md +12 -15
  10. package/.bkit/core/.bkit/comparison.md +66 -14
  11. package/.bkit/core/.bkit/install.md +31 -8
  12. package/.bkit/core/.bkit/jsonl.md +0 -1
  13. package/.bkit/core/.bkit/prompts.md +14 -13
  14. package/.bkit/core/.bkit/providers.md +92 -26
  15. package/.bkit/core/.bkit/templates.md +38 -11
  16. package/.bkit/core/.bkit/workflows.md +63 -41
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
  18. package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
  19. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
  20. package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
  21. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
  22. package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
  23. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
  24. package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
  25. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  26. package/.bkit/core/docs/templates/bkit-plan.md +6 -3
  27. package/.bkit/core/engine/checks/after/auth.ts +32 -0
  28. package/.bkit/core/engine/checks/after/github.ts +4 -4
  29. package/.bkit/core/engine/checks/after/index.ts +36 -50
  30. package/.bkit/core/engine/checks/after/managed.ts +40 -0
  31. package/.bkit/core/engine/checks/before/index.ts +5 -4
  32. package/.bkit/core/engine/checks/before/mcp.ts +60 -54
  33. package/.bkit/core/engine/checks/status-holes.ts +1 -1
  34. package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
  35. package/.bkit/core/engine/checks/tips/detect.ts +144 -0
  36. package/.bkit/core/engine/checks/tips/index.ts +174 -0
  37. package/.bkit/core/engine/cli.ts +57 -9
  38. package/.bkit/core/engine/commands/install/doctor.ts +5 -1
  39. package/.bkit/core/engine/commands/install/install.ts +39 -9
  40. package/.bkit/core/engine/commands/install/uninstall.ts +32 -18
  41. package/.bkit/core/engine/commands/install/upgrade.ts +15 -28
  42. package/.bkit/core/engine/commands/launch.ts +33 -11
  43. package/.bkit/core/engine/commands/tips.ts +16 -0
  44. package/.bkit/core/engine/commands/workflow/runs.ts +57 -16
  45. package/.bkit/core/engine/commands/workflow/runtime.ts +10 -0
  46. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  47. package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
  48. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
  49. package/.bkit/core/engine/install/cloud-env.ts +7 -21
  50. package/.bkit/core/engine/install/hosts.ts +21 -0
  51. package/.bkit/core/engine/install/managed-block.ts +36 -0
  52. package/.bkit/core/engine/install/manifest.ts +46 -4
  53. package/.bkit/core/engine/install/modules/antigravity.ts +8 -7
  54. package/.bkit/core/engine/install/modules/claude.ts +6 -6
  55. package/.bkit/core/engine/install/modules/cloud.ts +2 -2
  56. package/.bkit/core/engine/install/modules/codex.ts +5 -5
  57. package/.bkit/core/engine/install/modules/core.ts +23 -9
  58. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  59. package/.bkit/core/engine/install/modules/opencode.ts +4 -4
  60. package/.bkit/core/engine/install/payload-links.ts +6 -10
  61. package/.bkit/core/engine/install/placeholders.ts +1 -1
  62. package/.bkit/core/engine/install/version-file.ts +17 -9
  63. package/.bkit/core/engine/install/write.ts +68 -1
  64. package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
  65. package/.bkit/core/engine/shared/package-roots.ts +8 -10
  66. package/.bkit/core/hooks/antigravity-hook.js +67 -0
  67. package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
  68. package/.bkit/core/hooks/gateguard-engine.js +16 -6
  69. package/.bkit/core/hooks/guardrails-read.js +23 -0
  70. package/.bkit/core/hooks/readguard-engine.js +259 -0
  71. package/.bkit/core/hooks/readguard-payload.js +67 -0
  72. package/.bkit/core/prompts/bkit-audit-generate.md +1 -0
  73. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -0
  74. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -0
  75. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -0
  76. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -0
  77. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -0
  78. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -0
  79. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -0
  80. package/.bkit/core/prompts/bkit-build-plan-execute.md +5 -1
  81. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -0
  82. package/.bkit/core/prompts/bkit-build-plan-verify.md +11 -3
  83. package/.bkit/core/prompts/bkit-build-summary.md +1 -0
  84. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -0
  85. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -0
  86. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -0
  87. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -0
  88. package/.bkit/core/prompts/bkit-debug-summary.md +1 -0
  89. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +1 -0
  90. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +1 -0
  91. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +1 -0
  92. package/.bkit/core/prompts/bkit-design-generate.md +9 -4
  93. package/.bkit/core/prompts/bkit-design-organise.md +1 -0
  94. package/.bkit/core/prompts/bkit-design-review-1.md +1 -0
  95. package/.bkit/core/prompts/bkit-design-review-2.md +1 -0
  96. package/.bkit/core/prompts/bkit-design-spike.md +1 -0
  97. package/.bkit/core/prompts/bkit-design-summary.md +1 -0
  98. package/.bkit/core/prompts/bkit-design-update.md +1 -0
  99. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -0
  100. package/.bkit/core/prompts/bkit-plan-complexity-split.md +3 -2
  101. package/.bkit/core/prompts/bkit-plan-generate.md +1 -0
  102. package/.bkit/core/prompts/bkit-plan-review-1.md +1 -0
  103. package/.bkit/core/prompts/bkit-plan-review-2.md +1 -0
  104. package/.bkit/core/prompts/bkit-plan-review-3.md +1 -0
  105. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +2 -1
  106. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +2 -1
  107. package/.bkit/core/prompts/bkit-plan-summary.md +1 -0
  108. package/.bkit/core/prompts/bkit-plan-update.md +2 -1
  109. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -0
  110. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -0
  111. package/.bkit/core/prompts/bkit-ship-summary.md +1 -0
  112. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -0
  113. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +1 -0
  114. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -0
  115. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -0
  116. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -0
  117. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -0
  118. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -0
  119. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +1 -0
  120. package/.bkit/core/workflows/bkit-build.md +33 -21
  121. package/.bkit/core/workflows/bkit-debug.md +29 -22
  122. package/.bkit/core/workflows/bkit-design.md +81 -38
  123. package/.bkit/core/workflows/bkit-plan.md +8 -2
  124. package/.bkit/core/workflows/bkit-ship.md +8 -2
  125. package/.bkit/shared/.agents/plugins/bkit/hooks.json +13 -3
  126. package/.bkit/shared/.claude/settings.json +19 -0
  127. package/.bkit/shared/.codex/hooks.json +21 -0
  128. package/.bkit/shared/.cursor/hooks.json +6 -1
  129. package/.bkit/shared/.opencode/opencode.json +1 -1
  130. package/.bkit/shared/docs/deployments.md +1 -1
  131. package/.bkit/shared/docs/testing.md +12 -1
  132. package/.bkit/templates/.github/dependabot.yml +6 -0
  133. package/.bkit/templates/.github/renovate.json5 +3 -3
  134. package/.bkit/templates/.github/workflows/bkit-ci.yml +0 -13
  135. package/.bkit/templates/.prettierignore +1 -1
  136. package/.bkit/templates/context/bkit-expo.md +22 -13
  137. package/.bkit/templates/context/bkit-github.md +20 -6
  138. package/.bkit/templates/context/bkit-inngest.md +10 -4
  139. package/.bkit/templates/context/bkit-maestro.md +5 -5
  140. package/.bkit/templates/context/bkit-playwright.md +3 -3
  141. package/.bkit/templates/context/bkit-sentry.md +6 -5
  142. package/.bkit/templates/context/bkit-stripe.md +31 -8
  143. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  144. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  145. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  146. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  147. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  148. package/.bkit/templates/slop-scan.config.json +7 -2
  149. package/CHANGELOG.md +50 -0
  150. package/LICENSE.md +21 -161
  151. package/README.md +61 -28
  152. package/dist/checks/after/auth.js +28 -0
  153. package/dist/checks/after/github.js +4 -4
  154. package/dist/checks/after/index.js +29 -45
  155. package/dist/checks/after/managed.js +40 -1
  156. package/dist/checks/before/index.js +5 -4
  157. package/dist/checks/before/mcp.js +53 -53
  158. package/dist/checks/status-holes.js +1 -1
  159. package/dist/checks/tips/catalogue.js +297 -0
  160. package/dist/checks/tips/detect.js +130 -0
  161. package/dist/checks/tips/index.js +146 -0
  162. package/dist/cli.js +47 -9
  163. package/dist/commands/install/doctor.js +5 -1
  164. package/dist/commands/install/install.js +27 -7
  165. package/dist/commands/install/uninstall.js +31 -16
  166. package/dist/commands/install/upgrade.js +15 -32
  167. package/dist/commands/launch.js +27 -11
  168. package/dist/commands/tips.js +10 -0
  169. package/dist/commands/workflow/runs.js +52 -16
  170. package/dist/commands/workflow/runtime.js +8 -0
  171. package/dist/commands/workflow/steps.js +1 -0
  172. package/dist/commands/workflow/tests.js +541 -4
  173. package/dist/commands/workflow/workstreams.js +4 -4
  174. package/dist/install/cloud-env.js +3 -14
  175. package/dist/install/hosts.js +22 -0
  176. package/dist/install/managed-block.js +36 -0
  177. package/dist/install/manifest.js +45 -4
  178. package/dist/install/modules/antigravity.js +8 -7
  179. package/dist/install/modules/claude.js +6 -6
  180. package/dist/install/modules/cloud.js +2 -2
  181. package/dist/install/modules/codex.js +5 -5
  182. package/dist/install/modules/core.js +14 -5
  183. package/dist/install/modules/cursor.js +6 -6
  184. package/dist/install/modules/opencode.js +4 -4
  185. package/dist/install/payload-links.js +5 -5
  186. package/dist/install/placeholders.js +1 -1
  187. package/dist/install/version-file.js +12 -3
  188. package/dist/install/write.js +61 -2
  189. package/dist/shared/package-roots.js +8 -11
  190. package/package.json +4 -6
  191. package/.bkit/core/LICENSE.md +0 -149
  192. package/.bkit/shared/LICENSE.md +0 -22
  193. package/.bkit/templates/LICENSE.md +0 -22
package/dist/cli.js CHANGED
@@ -13,6 +13,7 @@ import { runComplyCommand } from "./commands/comply.js";
13
13
  import { runHarvestCommand } from "./commands/harvest.js";
14
14
  import { runAnalysisCommand } from "./commands/analysis.js";
15
15
  import { runTelemetryCommand } from "./commands/telemetry.js";
16
+ import { runTipsCommand } from "./commands/tips.js";
16
17
  import { runUpgradeCommand } from "./commands/install/upgrade.js";
17
18
  import { runUninstallCommand } from "./commands/install/uninstall.js";
18
19
  import { runInstall } from "./commands/install/install.js";
@@ -41,6 +42,7 @@ export const CLASSIC_VERBS = new Set([
41
42
  "harvest",
42
43
  "analysis",
43
44
  "telemetry",
45
+ "tips",
44
46
  "cursor",
45
47
  "opencode",
46
48
  "help",
@@ -70,7 +72,7 @@ export function parseComplyPhase(value) {
70
72
  // Bare module-flag tokens accepted on the CLI. `opencode` (value-bearing) is
71
73
  // intercepted by a dedicated branch in parseArgs before this set is consulted; the
72
74
  // generic check only ever validates claude/cursor/codex. `full`, `core` and `cloud`
73
- // are NOT accepted as bare flags: use `--auto=<claude|cursor>`; core is implicit.
75
+ // are NOT accepted as bare flags: use `--auto=<variant>`; core is implicit.
74
76
  // There is no dependency-updater flag. Copy an example; CI warns when none is present.
75
77
  const MODULE_FLAGS = new Set(["claude", "cursor", "opencode", "codex", "antigravity"]);
76
78
  // ALL_MODULES — every non-opt-in module, core first. Used to expand a bare/full
@@ -158,6 +160,10 @@ export function parseArgs(argv) {
158
160
  verb = "telemetry";
159
161
  args.shift();
160
162
  }
163
+ else if (firstArg === "tips") {
164
+ verb = "tips";
165
+ args.shift();
166
+ }
161
167
  else if (firstArg === "cursor" || firstArg === "opencode") {
162
168
  verb = firstArg;
163
169
  args.shift();
@@ -186,6 +192,8 @@ export function parseArgs(argv) {
186
192
  let opencodeProvider = null;
187
193
  let complyPhase = null;
188
194
  let telemetrySubverb = null;
195
+ let tipsAll = false;
196
+ let tipsWorkflow = null;
189
197
  // For `telemetry` verb: extract the sub-verb from the first remaining positional arg
190
198
  if (verb === "telemetry") {
191
199
  const subVerbArg = args[0];
@@ -244,7 +252,7 @@ export function parseArgs(argv) {
244
252
  console.error(`[bkit] --phase requires a value: --phase=<${COMPLY_PHASES.join("|")}>. Run \`bkit help\` for usage.`);
245
253
  process.exit(1);
246
254
  }
247
- // Value-bearing flag: --auto=<claude|cursor> — cloud-agent (auto-dispatch) lane;
255
+ // Value-bearing flag: --auto=<variant> (CLOUD_VARIANTS) — cloud-agent (auto-dispatch) lane;
248
256
  // sets the internal `cloud` module. Bare `--auto` (no variant) is accepted only on
249
257
  // uninstall (variant read from package.json).
250
258
  if (flag === "auto") {
@@ -302,6 +310,21 @@ export function parseArgs(argv) {
302
310
  moduleFlags.add("opencode");
303
311
  continue;
304
312
  }
313
+ // Tips-only flags: --all prints every firing tip; --workflow=<name> puts the tips that
314
+ // matter in that workflow first and prints one.
315
+ if (flag === "all" && verb === "tips") {
316
+ tipsAll = true;
317
+ continue;
318
+ }
319
+ if (flag.startsWith("workflow=") && verb === "tips") {
320
+ const value = flag.slice("workflow=".length);
321
+ tipsWorkflow = parseComplyPhase(value);
322
+ if (tipsWorkflow === null) {
323
+ console.error(`[bkit] Unknown workflow: "${value}". Valid values: ${COMPLY_PHASES.join(", ")}`);
324
+ process.exit(1);
325
+ }
326
+ continue;
327
+ }
305
328
  // Uninstall-specific flags (accepted for all verbs that use them)
306
329
  if (flag === "dry-run") {
307
330
  uninstallFlags.dryRun = true;
@@ -386,6 +409,8 @@ export function parseArgs(argv) {
386
409
  opencodeProvider,
387
410
  complyPhase,
388
411
  telemetrySubverb,
412
+ tipsAll,
413
+ tipsWorkflow,
389
414
  };
390
415
  }
391
416
  export function printUsage() {
@@ -395,7 +420,8 @@ Usage:
395
420
  bkit install <module-flags> Install (or re-sync) the named modules + the implicit
396
421
  core foundation. At least one module flag is REQUIRED —
397
422
  a bare \`bkit install\` errors (name the modules below).
398
- Hosts compose: --claude --cursor --codex --opencode=<provider>.
423
+ Hosts compose: --claude --cursor --codex --antigravity
424
+ --opencode=<provider>.
399
425
  bkit check Dry-run — drift-check everything already installed (no
400
426
  module flags). Exits 1 when a managed file needs
401
427
  re-rendering. Copies under .bkit/templates/ are refreshed by
@@ -422,6 +448,13 @@ Usage:
422
448
  targeted uninstall leaves core untouched.
423
449
  bkit doctor Read-only preflight + post-install advisory replay.
424
450
  Diagnose token surfaces and config drift. Exits 0.
451
+ bkit tips [--workflow=<name>] [--all]
452
+ Setup tips: what this repo has not set up yet, most useful
453
+ first, each with a sentence to ask your agent. Top three
454
+ by default; --workflow=design|plan|build|debug|ship puts
455
+ the tips that matter there first and prints one (each
456
+ workflow runs this at its close); --all lists every one.
457
+ Local checks only. Exits 0.
425
458
  bkit status Read-only host/provider status. Reports current host+provider
426
459
  (sampled from .opencode/opencode.json, .claude/, .cursor/).
427
460
  Writes nothing. Exits 0.
@@ -491,14 +524,15 @@ Module flags (composable; symmetric install ↔ uninstall):
491
524
  Provider value is REQUIRED. Supported: openrouter, ollama,
492
525
  opencode-zen, opencode-go (opencode-native gateways;
493
526
  auth via BKIT_OPENCODE_API_KEY).
494
- Ships .opencode/** (agents, commands, opencode.json, bkit-gateguard.js).
527
+ Ships .opencode/** (agents, commands, opencode.json, bkit-gateguard.js,
528
+ bkit-readguard.js).
495
529
  Configure your provider key; verify with \`bkit doctor\`. All installed
496
530
  providers tracked in bkit.opencodeProviders.
497
531
  --codex Codex CLI host. BARE flag — takes no value: Codex runs on one gateway
498
532
  (openai), so only --opencode is provider-pluggable. Ships .codex/agents/*.toml
499
- + .codex/hooks.json + .codex/hooks/bkit-gateguard.cjs, plus the workflow skills
500
- (.agents/skills/bkit-*/). Codex loads project-local hooks ONLY once the
501
- .codex/ layer is trusted — until then GateGuard is installed and never fires.
533
+ + .codex/hooks.json + .codex/hooks/bkit-{gateguard,guardrails,readguard}.cjs,
534
+ plus the workflow skills (.agents/skills/bkit-*/). Codex loads project-local
535
+ hooks ONLY once the .codex/ layer is trusted — until then they never fire.
502
536
  --antigravity Google Antigravity IDE host. BARE flag — takes no value: Antigravity runs
503
537
  on one gateway (google). Installs as a workspace PLUGIN at
504
538
  .agents/plugins/bkit/ — plugin.json + skills/bkit-*/SKILL.md (workflow
@@ -600,7 +634,7 @@ export function validateModuleFlagsForVerb(verb, moduleFlags) {
600
634
  if (verb === "install" && moduleFlags.size === 0) {
601
635
  return ("[bkit] `bkit install` requires at least one module flag. Name what to install: " +
602
636
  "--claude, --cursor, --codex, --antigravity, --opencode=<provider> (plus opt-in " +
603
- "--auto=<claude|cursor>). Run `bkit help` for usage.");
637
+ `--auto=<${CLOUD_VARIANTS.join("|")}>). Run \`bkit help\` for usage.`);
604
638
  }
605
639
  if ((verb === "check" || verb === "upgrade") && moduleFlags.size > 0) {
606
640
  return (`[bkit] \`bkit ${verb}\` takes no module flags — it operates on everything already ` +
@@ -621,7 +655,7 @@ export async function main() {
621
655
  process.exitCode = commandExit;
622
656
  return;
623
657
  }
624
- const { verb, modules, moduleFlags, uninstallFlags, upgradeFlags, tracker, cloudVariant, opencodeProvider, complyPhase, telemetrySubverb, } = parseArgs(process.argv.slice(2));
658
+ const { verb, modules, moduleFlags, uninstallFlags, upgradeFlags, tracker, cloudVariant, opencodeProvider, complyPhase, telemetrySubverb, tipsAll, tipsWorkflow, } = parseArgs(process.argv.slice(2));
625
659
  // A bare `bkit` (no arguments) means no command was given: print usage and exit non-zero
626
660
  // (2 = usage error), distinct from an explicit `bkit help` / `--help` (verb "help"), which
627
661
  // prints the same usage and exits 0. parseArgs still defaults no-args to the "help" verb.
@@ -649,6 +683,10 @@ export async function main() {
649
683
  runTelemetryCommand(telemetrySubverb, complyPhase);
650
684
  return;
651
685
  }
686
+ if (verb === "tips") {
687
+ runTipsCommand(tipsAll, tipsWorkflow);
688
+ return;
689
+ }
652
690
  // Launcher verbs — exec the GUI app binary with .bkit/.env merged into the env
653
691
  // so that MCP token placeholders (BKIT_GH_TOKEN, BKIT_OPENCODE_API_KEY, …) resolve correctly
654
692
  // even when launched from the Dock/Finder (macOS GUI-isolation).
@@ -8,6 +8,7 @@ import { LOG_PREFIX, setLogPrefix } from "../../shared/log-prefix.js";
8
8
  import { getCoreRoot, getSharedRoot, getTemplatesRoot } from "../../shared/package-roots.js";
9
9
  import { runPreflight } from "../../checks/before/index.js";
10
10
  import { runPostInstallCheck, formatChecklist, writeAdvisoriesArtifact, } from "../../checks/after/index.js";
11
+ import { collectTips } from "../../checks/tips/index.js";
11
12
  import { parseDotenv } from "../../install/cloud-env.js";
12
13
  /**
13
14
  * `bkit status` — read-only host/provider status.
@@ -118,7 +119,9 @@ export async function runDoctor(modules, opencodeProvider) {
118
119
  });
119
120
  }
120
121
  }
121
- const banner = formatChecklist(allFindings, suppressed);
122
+ const { tips, suppressed: suppressedTips } = collectTips(process.cwd());
123
+ suppressed.push(...suppressedTips);
124
+ const banner = formatChecklist(allFindings, suppressed, tips);
122
125
  if (banner) {
123
126
  console.log(banner);
124
127
  }
@@ -131,6 +134,7 @@ export async function runDoctor(modules, opencodeProvider) {
131
134
  version: getInstallingVersion(),
132
135
  logPrefix: LOG_PREFIX,
133
136
  suppressed,
137
+ tips,
134
138
  });
135
139
  // opencode host diagnostics: report required tools and cred presence per provider.
136
140
  // Never echoes key values — only reports present/absent.
@@ -10,6 +10,7 @@ import { LOG_PREFIX, setLogPrefix } from "../../shared/log-prefix.js";
10
10
  import { detectInstalledModules, reportCheckDrift } from "./check.js";
11
11
  import { runPreflight } from "../../checks/before/index.js";
12
12
  import { formatChecklist, readChangelogVersionDelta, runPostInstallCheck, writeAdvisoriesArtifact, } from "../../checks/after/index.js";
13
+ import { collectTips } from "../../checks/tips/index.js";
13
14
  import { findMissingOwnedHooks, detectOwnedHookMissing } from "../../checks/after/managed.js";
14
15
  import { resolveTokens } from "../../install/placeholders.js";
15
16
  import { parseModelLookup, applyModelOverrides, buildOpencodeModelLookup, buildAntigravityModelLookup, parseEffortMap, } from "../../render/models.js";
@@ -182,6 +183,19 @@ export function detectOpencodeProviders(cwd) {
182
183
  }
183
184
  return [];
184
185
  }
186
+ /**
187
+ * Re-run Phase 1 detection after the writes. The Phase 1 advisory seeds (the first
188
+ * `seedCount` entries of `current`) are replaced by the fresh ones; advisories pushed by
189
+ * modules during dispatch are kept. Fresh blockers are returned so the caller fails on them.
190
+ */
191
+ export function refreshPreflightAfterWrites(modules, cwd, issueTracker, seedCount, current) {
192
+ const moduleAdvisories = current.slice(seedCount);
193
+ const fresh = runPreflight(modules, cwd, undefined, issueTracker);
194
+ return {
195
+ advisories: [...fresh.advisories, ...moduleAdvisories],
196
+ blockers: fresh.blockers,
197
+ };
198
+ }
185
199
  /** `bkit install`, and `bkit check` (the same pipeline, dry-run). */
186
200
  export async function runInstall(args) {
187
201
  const { verb, modules, tracker, cloudVariant, opencodeProvider, uninstallFlags } = args;
@@ -297,9 +311,7 @@ export async function runInstall(args) {
297
311
  effortMap = parseEffortMap(promptsMdPath);
298
312
  }
299
313
  // Seed preflight advisories into ctx so modules can accumulate into the same list.
300
- const advisories = [
301
- ...preflightAdvisories,
302
- ];
314
+ const advisories = [...preflightAdvisories];
303
315
  const ws = { writes: [] };
304
316
  const postDispatch = [];
305
317
  // Symmetric cloud/tracker constraint (FINAL SCOPE decision 3/4) — see
@@ -422,10 +434,11 @@ export async function runInstall(args) {
422
434
  // banner above. `check` (dryRun) wrote nothing, so its Phase 1 findings already describe
423
435
  // the current state and are kept as-is. Module-accumulated advisories (pushed during
424
436
  // dispatch) are preserved; only the Phase 1 seeds are replaced, in their original order.
437
+ let postWriteBlockers = [];
425
438
  if (!dryRun) {
426
- const moduleAdvisories = advisories.slice(preflightAdvisories.length);
427
- const { advisories: freshPreflightAdvisories } = runPreflight(effectiveModules, process.cwd(), undefined, issueTracker);
428
- ctx.advisories = [...freshPreflightAdvisories, ...moduleAdvisories];
439
+ const refreshed = refreshPreflightAfterWrites(effectiveModules, process.cwd(), issueTracker, preflightAdvisories.length, advisories);
440
+ ctx.advisories = refreshed.advisories;
441
+ postWriteBlockers = refreshed.blockers;
429
442
  }
430
443
  // --- Phase 3: Post-install checks (re-detect + unified output) ---
431
444
  // Runs for both install AND check — detectors are read-only, so check produces
@@ -445,13 +458,19 @@ export async function runInstall(args) {
445
458
  }
446
459
  const suppressed = [];
447
460
  const postFindings = runPostInstallCheck(ctx.advisories, process.cwd(), suppressed);
461
+ if (postWriteBlockers.length > 0) {
462
+ console.log(`${LOG_PREFIX} Preflight blockers appeared after the writes — files are already written; fix the blocker and re-run.`);
463
+ postFindings.unshift(...postWriteBlockers);
464
+ }
448
465
  // check only: install has just written every hook file of the modules it dispatched, and a
449
466
  // missing bkit-cloud-bootstrap.sh after `install --claude` is not that run's fault.
450
467
  const missingHooks = dryRun ? findMissingOwnedHooks(process.cwd(), effectiveModules) : [];
451
468
  const missingHooksFinding = detectOwnedHookMissing(missingHooks);
452
469
  if (missingHooksFinding)
453
470
  postFindings.push(missingHooksFinding);
454
- const banner = formatChecklist(postFindings, suppressed);
471
+ const { tips, suppressed: suppressedTips } = collectTips(process.cwd());
472
+ suppressed.push(...suppressedTips);
473
+ const banner = formatChecklist(postFindings, suppressed, tips);
455
474
  if (banner)
456
475
  console.log(banner);
457
476
  writeAdvisoriesArtifact(postFindings, {
@@ -460,6 +479,7 @@ export async function runInstall(args) {
460
479
  version: getInstallingVersion(),
461
480
  logPrefix: LOG_PREFIX,
462
481
  suppressed,
482
+ tips,
463
483
  });
464
484
  // Check mode: exit 1 on drift (see reportCheckDrift).
465
485
  if (dryRun) {
@@ -384,6 +384,7 @@ export async function runUninstall(modules, ctx) {
384
384
  deleted: [],
385
385
  stripped: [],
386
386
  preserved: [],
387
+ absent: [],
387
388
  decisions: [],
388
389
  dryRun: ctx.dryRun,
389
390
  };
@@ -413,7 +414,13 @@ export async function runUninstall(modules, ctx) {
413
414
  seen.add(summary.file);
414
415
  const absPath = path.join(ctx.cwd, summary.file);
415
416
  switch (summary.decision) {
416
- case "skip-absent":
417
+ case "skip-absent": {
418
+ result.absent.push(summary.file);
419
+ if (!ctx.dryRun) {
420
+ console.log(`${ctx.logPrefix} absent: ${summary.file} (${summary.reason})`);
421
+ }
422
+ break;
423
+ }
417
424
  case "skip-modified":
418
425
  case "skip-unknown":
419
426
  case "preserve": {
@@ -570,7 +577,8 @@ export async function runUninstall(modules, ctx) {
570
577
  }
571
578
  // Clean up .agents/ bkit-prefix mirror files
572
579
  // (.claude/commands/bkit-*.md, .claude/agents/bkit-*.md, .opencode/agents/bkit-*.md, etc.)
573
- if (!ctx.dryRun) {
580
+ // A dry run lists the same paths in result.deleted and removes nothing.
581
+ {
574
582
  const mirrorDirs = [
575
583
  // Each host's mirror dirs are gated on its own module so a targeted
576
584
  // uninstall (e.g. --claude / --auto) leaves other hosts
@@ -598,9 +606,11 @@ export async function runUninstall(modules, ctx) {
598
606
  if (!f.startsWith("bkit-") || !(f.endsWith(".md") || f.endsWith(".toml")))
599
607
  continue;
600
608
  const absFile = path.join(absDir, f);
601
- fs.rmSync(absFile, { force: true });
609
+ if (!ctx.dryRun)
610
+ fs.rmSync(absFile, { force: true });
602
611
  result.deleted.push(path.join(dir, f));
603
- console.log(`${ctx.logPrefix} delete mirror: ${path.join(dir, f)}`);
612
+ if (!ctx.dryRun)
613
+ console.log(`${ctx.logPrefix} delete mirror: ${path.join(dir, f)}`);
604
614
  }
605
615
  }
606
616
  catch (err) {
@@ -628,9 +638,12 @@ export async function runUninstall(modules, ctx) {
628
638
  const abs = path.join(absDir, d);
629
639
  if (!fs.statSync(abs).isDirectory())
630
640
  continue;
631
- fs.rmSync(abs, { recursive: true, force: true });
641
+ if (!ctx.dryRun)
642
+ fs.rmSync(abs, { recursive: true, force: true });
632
643
  result.deleted.push(path.join(skillsDir, d));
633
- console.log(`${ctx.logPrefix} delete mirror: ${path.join(skillsDir, d)}`);
644
+ if (!ctx.dryRun) {
645
+ console.log(`${ctx.logPrefix} delete mirror: ${path.join(skillsDir, d)}`);
646
+ }
634
647
  }
635
648
  }
636
649
  catch (err) {
@@ -740,7 +753,7 @@ export async function runUninstall(modules, ctx) {
740
753
  const versionFile = path.join(ctx.cwd, ".bkit", "version");
741
754
  const existing = readBkitVersion(versionFile);
742
755
  if (existing) {
743
- const { canonicalHashes, pruned } = mergeCanonicalHashes(ctx.cwd, existing.canonicalHashes, {});
756
+ const { canonicalHashes, pruned } = mergeCanonicalHashes(ctx.cwd, existing.canonicalHashes, {}, result.deleted);
744
757
  if (pruned > 0) {
745
758
  console.log(`${ctx.logPrefix}${ctx.dryRun ? " [dry-run]" : ""} update version pin: .bkit/version (pruned ${pruned})`);
746
759
  if (!ctx.dryRun) {
@@ -859,13 +872,15 @@ export async function runUninstallCommand(modules, opencodeProvider, uninstallFl
859
872
  const moduleList = [...modules];
860
873
  console.log(`${LOG_PREFIX} Running uninstall${uninstallCtx.dryRun ? " (dry-run)" : ""}...`);
861
874
  const result = await runUninstall(moduleList, uninstallCtx);
862
- const totalDeleted = result.deleted.length;
863
- const totalStripped = result.stripped.length;
864
- const totalPreserved = result.preserved.length;
865
- if (uninstallCtx.dryRun) {
866
- console.log(`${LOG_PREFIX} [dry-run] Would delete: ${totalDeleted}, strip: ${totalStripped}, preserve: ${totalPreserved}`);
867
- }
868
- else {
869
- console.log(`${LOG_PREFIX} Done. Deleted: ${totalDeleted}, stripped: ${totalStripped}, preserved: ${totalPreserved}`);
870
- }
875
+ console.log(uninstallSummaryLine(result, LOG_PREFIX));
876
+ }
877
+ /** The closing totals line of an uninstall run (dry-run wording when `result.dryRun`). */
878
+ export function uninstallSummaryLine(result, logPrefix) {
879
+ const deleted = result.deleted.length;
880
+ const stripped = result.stripped.length;
881
+ const preserved = result.preserved.length;
882
+ const absent = result.absent.length;
883
+ return result.dryRun
884
+ ? `${logPrefix} [dry-run] Would delete: ${deleted}, strip: ${stripped}, preserve: ${preserved}, already absent: ${absent}`
885
+ : `${logPrefix} Done. Deleted: ${deleted}, stripped: ${stripped}, preserved: ${preserved}, already absent: ${absent}`;
871
886
  }
@@ -30,6 +30,7 @@ import { getInstallingVersion, requireOpencodeProvider, detectOpencodeProviders,
30
30
  import { setLogPrefix } from "../../shared/log-prefix.js";
31
31
  import { getInstallManifest, getModuleManifest, DEFAULT_ISSUE_TRACKER, parseIssueTracker, } from "../../install/manifest.js";
32
32
  import { OPTIN_MODULES } from "../../install/manifest.js";
33
+ import { detectInstalledHostModules } from "../../install/hosts.js";
33
34
  import { detectInstalledModules } from "./check.js";
34
35
  import { remapTemplateDest } from "../../install/template-copies.js";
35
36
  import { CLAUDE_CLOUD_RELPATH, CURSOR_CLOUD_RELPATH, writeClaudeCloudDoc, writeCursorCloudDoc, writeNetworkAllowlistArtifact, writeCursorCliPermissionsArtifact, } from "../../install/cloud-env.js";
@@ -332,25 +333,6 @@ export function updateCanonicalHashesAfterUpgrade(result, options) {
332
333
  };
333
334
  writeBkitVersion(versionFile, updated);
334
335
  }
335
- /**
336
- * Detect which host modules a consumer has installed, by the presence of each host's
337
- * source-rendered agents directory. Used by `bkit upgrade` to re-render only the hosts
338
- * the consumer installed — never force-creating an opencode/cursor tree.
339
- */
340
- export function detectInstalledHostModules(cwd) {
341
- const mods = new Set();
342
- if (fs.existsSync(path.join(cwd, ".claude", "agents")))
343
- mods.add("claude");
344
- if (fs.existsSync(path.join(cwd, ".cursor", "agents")))
345
- mods.add("cursor");
346
- if (fs.existsSync(path.join(cwd, ".opencode", "agents")))
347
- mods.add("opencode");
348
- if (fs.existsSync(path.join(cwd, ".codex", "agents")))
349
- mods.add("codex");
350
- if (fs.existsSync(path.join(cwd, ".agents", "plugins", "bkit", "plugin.json")))
351
- mods.add("antigravity");
352
- return mods;
353
- }
354
336
  /**
355
337
  * Resolve the newest published @cbartens/bkit version from the registry for
356
338
  * `bkit upgrade --latest`. Shells out to `pnpm view` (honours the consumer's
@@ -517,9 +499,6 @@ export async function runUpgradeCommand(upgradeFlags) {
517
499
  collectPayload(entAbs, entRel, skipTopDirs);
518
500
  }
519
501
  else if (ent.isFile()) {
520
- // Each payload root's LICENSE.md is package metadata, never an install source.
521
- if (ent.name === "LICENSE.md")
522
- continue;
523
502
  // Single shared dotfile remap (gitignore → .gitignore, npmignore → .npmignore).
524
503
  const relPath = remapTemplateDest(entRel);
525
504
  // `.claude/bkit-cloud.md` + `.cursor/bkit-cloud.md` are GENERATED output files
@@ -532,15 +511,22 @@ export async function runUpgradeCommand(upgradeFlags) {
532
511
  continue;
533
512
  if (relPath === MCP_ROOT_RELPATH || relPath === CURSOR_MCP_RELPATH)
534
513
  continue;
535
- // Skip opt-in-module files the consumer hasn't opted into (dest absent).
514
+ const entry = entryByPath.get(relPath);
515
+ const ownerModule = entry?.module;
516
+ // Skip opt-in-module files the consumer hasn't opted into: dest absent and the owning
517
+ // module not detected as installed. A detected opt-in host (opencode / codex /
518
+ // antigravity) gets the files a newer release adds; `cloud` has no install sentinel,
519
+ // so its files upgrade only when present. opencode.json is created only when its
520
+ // provider resolves — never written with raw `@@OPENCODE_*@@` sentinels.
536
521
  if (optInPaths.has(relPath) && !fs.existsSync(path.join(process.cwd(), relPath))) {
537
- continue;
522
+ const hostInstalled = ownerModule !== undefined && installedModules.has(ownerModule);
523
+ if (!hostInstalled || (relPath === OPENCODE_JSON_RELPATH && !upgradeOpencodeProvider)) {
524
+ continue;
525
+ }
538
526
  }
539
- const entry = entryByPath.get(relPath);
540
527
  // Skip host-module files when that module is not installed — upgrade updates
541
528
  // only what the consumer opted into, never force-creating a new module. opt-ins are
542
- // handled by the dest-presence check above; core + entry-less files always pass.
543
- const ownerModule = entry?.module;
529
+ // handled by the check above; core + entry-less files always pass.
544
530
  if (ownerModule &&
545
531
  ownerModule !== "core" &&
546
532
  !optInPaths.has(relPath) &&
@@ -585,11 +571,8 @@ export async function runUpgradeCommand(upgradeFlags) {
585
571
  console.log(`${LOG_PREFIX} ${templateReport}`);
586
572
  // Payload view links — the same sync install runs (`.bkit/core` + `.bkit/shared`
587
573
  // point into the installed package). Never clobbers a real directory; a platform
588
- // refusal is reported, never fatal. Throwaway WriteSet: links carry no hash.
589
- const linkChanges = syncPayloadLinks(process.cwd(), {
590
- dryRun: upgradeFlags.dryRun,
591
- ws: { writes: [] },
592
- });
574
+ // refusal is reported, never fatal. Links carry no hash.
575
+ const linkChanges = syncPayloadLinks(process.cwd(), { dryRun: upgradeFlags.dryRun });
593
576
  const linkReport = formatPayloadLinkChanges(linkChanges);
594
577
  if (linkReport)
595
578
  console.log(`${LOG_PREFIX} ${linkReport}`);
@@ -72,11 +72,28 @@ export function isAlreadyRunning(binaryPath) {
72
72
  });
73
73
  return !result.error && result.status === 0 && result.stdout.trim().length > 0;
74
74
  }
75
+ /** `pgrep -f` pattern for OpenCode 2.0's shared background server (`<dir>/opencode serve --service`). */
76
+ const OPENCODE_SERVER_PATTERN = "(^|/)opencode serve( |$)";
77
+ /**
78
+ * Return true if OpenCode 2.0's shared background server (`opencode serve`) is running.
79
+ * It outlives the desktop app and every client attaches to it, so it holds the stale env.
80
+ */
81
+ export function isOpencodeServerRunning() {
82
+ return isAlreadyRunning(OPENCODE_SERVER_PATTERN);
83
+ }
84
+ const OPENCODE_SERVER_ADVICE = ` OpenCode 2.0 runs one shared background server for every client (TUI, web,\n` +
85
+ ` desktop) and captures its environment once, at first start. A newly opened\n` +
86
+ ` window talks to that server and still sees the OLD env, so the per-repo tokens\n` +
87
+ ` in .bkit/.env are not picked up. Stop the shared server, then re-launch:\n` +
88
+ ` opencode service stop && pnpm bkit opencode\n` +
89
+ ` (that stops every opencode window, not just this one; quitting the app fully\n` +
90
+ ` and re-running works too)`;
75
91
  /**
76
92
  * Launch `app` with .bkit/.env merged into its environment.
77
93
  *
78
94
  * - Loads `.bkit/.env` from `cwd` and merges into process.env (process.env wins).
79
- * - Detects an already-running instance via pgrep; warns + exits non-zero if found
95
+ * - Detects an already-running instance via pgrep (for opencode also the 2.0 shared
96
+ * background server `opencode serve`); warns if found
80
97
  * (the running process will not inherit the new env even if the binary hands off).
81
98
  * - For Cursor: passes `cwd` as a positional arg so it opens the repo folder.
82
99
  * - Spawns detached so the terminal is not blocked by the GUI app.
@@ -89,20 +106,19 @@ export async function launchApp(app, cwd) {
89
106
  process.exit(1);
90
107
  }
91
108
  const { binPath } = resolved;
92
- if (isAlreadyRunning(binPath)) {
109
+ const appRunning = isAlreadyRunning(binPath);
110
+ const serverRunning = app === "opencode" && isOpencodeServerRunning();
111
+ if (appRunning) {
93
112
  console.warn(`[bkit] ${app} is already running — opening folder in a new window, but the\n` +
94
113
  `environment from .bkit/.env will NOT take effect (the running process keeps\n` +
95
114
  `its original env). If you need per-repo tokens, quit ${app} fully (Cmd+Q)\n` +
96
115
  `and re-run: pnpm bkit ${app}` +
97
- (app === "opencode"
98
- ? `\n\n OpenCode 2.0 runs one shared background server for every client (TUI, web,\n` +
99
- ` desktop) and captures its environment once, at first start. A newly opened\n` +
100
- ` window talks to that server and still sees the OLD env, so the per-repo tokens\n` +
101
- ` in .bkit/.env are not picked up. Stop the shared server, then re-launch:\n` +
102
- ` opencode service stop && pnpm bkit opencode\n` +
103
- ` (that stops every opencode window, not just this one; quitting the app fully\n` +
104
- ` and re-running works too)`
105
- : ""));
116
+ (app === "opencode" ? `\n\n${OPENCODE_SERVER_ADVICE}` : ""));
117
+ }
118
+ else if (serverRunning) {
119
+ console.warn(`[bkit] the opencode background server (opencode serve) is already running — the\n` +
120
+ `environment from .bkit/.env will NOT take effect (the server keeps the env it\n` +
121
+ `started with, even though the desktop app itself is not open).\n\n${OPENCODE_SERVER_ADVICE}`);
106
122
  }
107
123
  // Cursor: pass repo dir so it opens the folder. opencode: no positional needed
108
124
  // (it reads opencode.json from cwd, and cwd is inherited via { cwd } spawn option).
@@ -0,0 +1,10 @@
1
+ // commands/tips.ts — `bkit tips [--workflow=<name>] [--all]`: print the setup tips that
2
+ // apply to this repo. Each workflow passes its name at its close and gets the one tip that
3
+ // matters most there; bare `bkit tips` prints the top three. Local checks only, no
4
+ // network; prints nothing when no tip fires; exits 0.
5
+ import { collectTips, formatTips } from "../checks/tips/index.js";
6
+ export function runTipsCommand(all, workflow, cwd = process.cwd()) {
7
+ const output = formatTips(collectTips(cwd).tips, { all, workflow });
8
+ if (output)
9
+ console.log(output);
10
+ }
@@ -746,8 +746,21 @@ const INTERVAL_FLAG = {
746
746
  type: "string",
747
747
  help: "seconds between polls (>= 1)",
748
748
  };
749
- const deps = (ctx) => ({
750
- gh: (args) => runGh(ctx.cwd, args),
749
+ /**
750
+ * `gh` pinned to `repo`: `--repo` is appended to every subcommand that takes it.
751
+ * `gh api` is left alone because its path already names the repo. No `repo` = `gh` unchanged.
752
+ */
753
+ export function repoScopedGh(gh, repo) {
754
+ if (repo === undefined)
755
+ return gh;
756
+ return (args) => (args[0] === "api" ? gh(args) : gh([...args, "--repo", repo]));
757
+ }
758
+ /** Whether `--repo` names a repo other than the checkout's own (local git then describes the wrong repo). */
759
+ function isForeignRepo(cwd, repo) {
760
+ return (repo !== undefined && resolveOwnerRepo(cwd)?.ownerRepo.toLowerCase() !== repo.toLowerCase());
761
+ }
762
+ const deps = (ctx, repo) => ({
763
+ gh: repoScopedGh((args) => runGh(ctx.cwd, args), repo),
751
764
  sleep: realSleep,
752
765
  log: ctx.log,
753
766
  });
@@ -1037,10 +1050,23 @@ function runGate(ctx) {
1037
1050
  const snapshot = str(f.snapshot);
1038
1051
  if (snapshot !== undefined) {
1039
1052
  const info = pr?.kind === "ok" ? pr.pr : undefined;
1040
- const dev = git(ctx.cwd, ["rev-parse", "origin/dev"]) ?? "";
1041
- const ancestor = runGit(ctx.cwd, ["merge-base", "--is-ancestor", "origin/dev", head]).ok;
1053
+ const repoFlag = str(f.repo);
1054
+ const foreign = isForeignRepo(ctx.cwd, repoFlag);
1055
+ // A foreign repo's dev and ancestry come from the API: the checkout's origin/dev is another repo's.
1056
+ let dev;
1057
+ let ancestor;
1058
+ if (foreign && repoFlag !== undefined) {
1059
+ const devRes = gh(["api", `repos/${repoFlag}/commits/dev`, "--jq", ".sha"]);
1060
+ dev = devRes.ok ? devRes.stdout.trim() : "";
1061
+ const cmp = gh(["api", `repos/${repoFlag}/compare/dev...${head}`, "--jq", ".status"]);
1062
+ ancestor = cmp.ok && ["ahead", "identical"].includes(cmp.stdout.trim());
1063
+ }
1064
+ else {
1065
+ dev = git(ctx.cwd, ["rev-parse", "origin/dev"]) ?? "";
1066
+ ancestor = runGit(ctx.cwd, ["merge-base", "--is-ancestor", "origin/dev", head]).ok;
1067
+ }
1042
1068
  const ciWorkflow = readBkitConfig(root).ciWorkflow;
1043
- const runs = gh([
1069
+ const runs = repoScopedGh(gh, repoFlag)([
1044
1070
  "run",
1045
1071
  "list",
1046
1072
  "--branch",
@@ -1132,7 +1158,9 @@ function devRequiresChecks(gh, repo) {
1132
1158
  }
1133
1159
  async function runRevalidate(ctx) {
1134
1160
  const f = ctx.flags;
1135
- const d = deps(ctx);
1161
+ const repoFlag = str(f.repo);
1162
+ const d = deps(ctx, repoFlag);
1163
+ const foreign = isForeignRepo(ctx.cwd, repoFlag);
1136
1164
  const branch = String(f.branch);
1137
1165
  const entry = String(f.entryHead);
1138
1166
  const codeHead = String(f.codeHead);
@@ -1140,8 +1168,9 @@ async function runRevalidate(ctx) {
1140
1168
  if (!["head-move", "gate-refusal"].includes(reason))
1141
1169
  throw new CommandError(EXIT.USAGE, "--reason must be head-move or gate-refusal");
1142
1170
  const status = path.resolve(ctx.cwd, String(f.file));
1143
- runGit(ctx.cwd, ["fetch", "origin", branch]);
1144
- const pr = probePr(ctx.cwd, { number: String(f.pr), state: "open", repo: str(f.repo) });
1171
+ if (!foreign)
1172
+ runGit(ctx.cwd, ["fetch", "origin", branch]);
1173
+ const pr = probePr(ctx.cwd, { number: String(f.pr), state: "open", repo: repoFlag });
1145
1174
  if (pr.kind === "unavailable") {
1146
1175
  ctx.log(pr.message);
1147
1176
  return EXIT.USE_MCP;
@@ -1155,15 +1184,22 @@ async function runRevalidate(ctx) {
1155
1184
  // CI must pass at the code head while the PR head adds bookkeeping only and dev
1156
1185
  // demands no status checks; otherwise at the PR head.
1157
1186
  let validated = codeHead;
1158
- const book = onlyBookkeeping(checkoutRoot(ctx.cwd), {
1159
- month: String(f.month),
1160
- fid: String(f.fid),
1161
- from: codeHead,
1162
- to: current,
1163
- });
1164
- if (!book.ok)
1187
+ if (foreign) {
1188
+ // The bookkeeping diff reads the checkout's git, which is not the named repo's history.
1189
+ ctx.log(`--repo ${repoFlag} is not this checkout's repo — bookkeeping diff skipped, validating at the PR head ${current}`);
1165
1190
  validated = current;
1166
- const repo = str(f.repo) ?? resolveOwnerRepo(ctx.cwd)?.ownerRepo;
1191
+ }
1192
+ else {
1193
+ const book = onlyBookkeeping(checkoutRoot(ctx.cwd), {
1194
+ month: String(f.month),
1195
+ fid: String(f.fid),
1196
+ from: codeHead,
1197
+ to: current,
1198
+ });
1199
+ if (!book.ok)
1200
+ validated = current;
1201
+ }
1202
+ const repo = repoFlag ?? resolveOwnerRepo(ctx.cwd)?.ownerRepo;
1167
1203
  if (repo !== undefined && devRequiresChecks(d.gh, repo)) {
1168
1204
  ctx.log(`dev requires status checks — validating at the PR head ${current}`);
1169
1205
  validated = current;