@biffo/cli 0.309.3 → 0.310.0

package/dist/index.js

@@ -12503,6 +12503,16 @@ function auditSiblingCoreDirectPaths(params) {
 // src/scripts/check-core-direct-paths.ts
 async function runCoreDirectPathsCheck(opts = {}) {
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  const usingSelfCheckDefaults = !opts.sibling && !opts.frontendSrc && !opts.coreSrc;
+  if (usingSelfCheckDefaults) {
+    const ownership = classifyRepoOwnership(root);
+    if (ownership === "satellite") {
+      console.log(
+        "\u2713 core-direct-paths guard: skipped \u2014 the self-check defaults compare this repo's own _skeletons/sibling-template scaffold against its own services/api/src, and a sibling/plugin repo has neither: no _skeletons/ at all, and its own services/api/ is an unrelated BFF, not core's route table. Pass --sibling/--frontend-src plus --estate (or --core-src) to audit a real sibling instead."
+      );
+      return;
+    }
+  }
   const sibling = opts.sibling ?? "sibling-template (self-check)";
   const frontendSrcDir = opts.frontendSrc ?? join48(root, "_skeletons", "sibling-template", "apps", "frontend", "src");
   let coreApiSrcDir;
@@ -12616,8 +12626,8 @@ async function runOwnershipCheck(argv) {
     const { stdout } = await execa("git", ["diff", "--cached", "--name-status"], { cwd: root });
     ({ changed: changedFiles, deleted: deletedFiles } = parseNameStatus(stdout));
     if (messageFile) {
-      const { readFileSync: readFileSync48, existsSync: existsSync59 } = await import("fs");
-      if (existsSync59(messageFile)) commitMessage = readFileSync48(messageFile, "utf8");
+      const { readFileSync: readFileSync48, existsSync: existsSync58 } = await import("fs");
+      if (existsSync58(messageFile)) commitMessage = readFileSync48(messageFile, "utf8");
     }
   } else {
     const base = process.env["GITHUB_BASE_REF"] ?? args[0];
@@ -14052,10 +14062,6 @@ async function runPipeTrapCheck() {
   console.log(`\u2713 Pipe-trap guard: no status-bearing command is piped away`);
 }
 
-// src/scripts/check-plugin-allowlist-convention.ts
-import { existsSync as existsSync50 } from "fs";
-import { join as join61 } from "path";
-
 // src/lib/plugin-allowlist-convention.ts
 import { readFileSync as readFileSync41 } from "fs";
 import { join as join60 } from "path";
@@ -14164,18 +14170,12 @@ Plugins would be rejected by require_service_principal (ADR-0009). Fix the glob,
 }
 
 // src/scripts/check-plugin-allowlist-convention.ts
-var REQUIRED_SOURCES = [
-  COMPUTE_MAIN_TF,
-  PLUGIN_TEMPLATE_MAIN_TF,
-  ALLOWLIST_MAIN_TF,
-  ALLOWLIST_VARIABLES_TF
-];
 async function runPluginAllowlistConventionCheck() {
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
-  const missing = REQUIRED_SOURCES.filter((relative11) => !existsSync50(join61(root, relative11)));
-  if (missing.length === REQUIRED_SOURCES.length) {
+  const ownership = classifyRepoOwnership(root);
+  if (ownership === "satellite") {
     console.log(
-      `\xB7 Plugin-allowlist convention guard: not applicable \u2014 ${missing.join(", ")} not found under ${root}. This is not a template/instance tree (a satellite repo never carries the plugin-allowlist Terraform modules). Skipping.`
+      `\xB7 Plugin-allowlist convention guard: not applicable \u2014 this is not a template/instance tree (${root}), so there is no modules/plugins/_template or modules/cloud/aws/plugin-allowlist Terraform to audit. A sibling app may carry its own unrelated modules/cloud/aws/compute for its own BFF; that is not this guard's concern. Skipping.`
     );
     return;
   }
@@ -14203,32 +14203,32 @@ async function runPluginAllowlistConventionCheck() {
 }
 
 // src/scripts/check-plugin-collisions.ts
-import { existsSync as existsSync52 } from "fs";
-import { join as join63 } from "path";
+import { existsSync as existsSync51 } from "fs";
+import { join as join62 } from "path";
 
 // src/lib/plugin-collision-guard.ts
-import { existsSync as existsSync51, readdirSync as readdirSync24, statSync as statSync15 } from "fs";
-import { join as join62 } from "path";
+import { existsSync as existsSync50, readdirSync as readdirSync24, statSync as statSync15 } from "fs";
+import { join as join61 } from "path";
 var PYTEST_SPECIAL = /* @__PURE__ */ new Set(["conftest.py"]);
 var IGNORED_DIRS = /* @__PURE__ */ new Set([".venv", "node_modules", "__pycache__", ".git", "dist", "build"]);
 function subdirectories(dir) {
-  if (!existsSync51(dir)) return [];
+  if (!existsSync50(dir)) return [];
   return readdirSync24(dir).filter((entry) => {
     if (IGNORED_DIRS.has(entry) || entry.startsWith(".")) return false;
     try {
-      return statSync15(join62(dir, entry)).isDirectory();
+      return statSync15(join61(dir, entry)).isDirectory();
     } catch {
       return false;
     }
   });
 }
 function regularPackagesOf(pluginDir2) {
-  return subdirectories(pluginDir2).filter((name) => existsSync51(join62(pluginDir2, name, "__init__.py"))).sort();
+  return subdirectories(pluginDir2).filter((name) => existsSync50(join61(pluginDir2, name, "__init__.py"))).sort();
 }
 function bareTestModulesOf(pluginDir2) {
-  const testsDir = join62(pluginDir2, "tests");
-  if (!existsSync51(testsDir)) return [];
-  if (existsSync51(join62(testsDir, "__init__.py"))) return [];
+  const testsDir = join61(pluginDir2, "tests");
+  if (!existsSync50(testsDir)) return [];
+  if (existsSync50(join61(testsDir, "__init__.py"))) return [];
   return readdirSync24(testsDir).filter((f) => f.endsWith(".py") && !PYTEST_SPECIAL.has(f)).sort();
 }
 function findCollisions(servicesDir, pluginDirs) {
@@ -14237,7 +14237,7 @@ function findCollisions(servicesDir, pluginDirs) {
   const gather = (kind, namesOf) => {
     const claims = /* @__PURE__ */ new Map();
     for (const plugin of plugins) {
-      for (const name of namesOf(join62(servicesDir, plugin))) {
+      for (const name of namesOf(join61(servicesDir, plugin))) {
         claims.set(name, [...claims.get(name) ?? [], plugin]);
       }
     }
@@ -14275,8 +14275,8 @@ function formatCollisions(collisions) {
 // src/scripts/check-plugin-collisions.ts
 async function runPluginCollisionCheck() {
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
-  const servicesDir = join63(root, "services");
-  if (!existsSync52(servicesDir)) {
+  const servicesDir = join62(root, "services");
+  if (!existsSync51(servicesDir)) {
     console.log("\u2713 plugin collision guard: no services/ directory \u2014 nothing to compare");
     return;
   }
@@ -14293,8 +14293,8 @@ async function runPluginCollisionCheck() {
 }
 
 // src/lib/plugin-terraform-guard.ts
-import { existsSync as existsSync53, readFileSync as readFileSync42, readdirSync as readdirSync25 } from "fs";
-import { dirname as dirname10, join as join64, relative as relative10, sep as sep4 } from "path";
+import { existsSync as existsSync52, readFileSync as readFileSync42, readdirSync as readdirSync25 } from "fs";
+import { dirname as dirname10, join as join63, relative as relative10, sep as sep4 } from "path";
 var SKIP_DIRS4 = /* @__PURE__ */ new Set(["node_modules", ".git", ".worktrees", "dist", ".venv", "__pycache__"]);
 var PLUGIN_MANIFEST_FILE2 = "biffo.plugin.json";
 function findPluginManifests(root) {
@@ -14309,9 +14309,9 @@ function findPluginManifests(root) {
     for (const entry of entries) {
       if (entry.isDirectory()) {
         if (SKIP_DIRS4.has(entry.name)) continue;
-        walk2(join64(dir, entry.name));
+        walk2(join63(dir, entry.name));
       } else if (entry.isFile() && entry.name === PLUGIN_MANIFEST_FILE2) {
-        found.push(relative10(root, join64(dir, entry.name)).split(sep4).join("/"));
+        found.push(relative10(root, join63(dir, entry.name)).split(sep4).join("/"));
       }
     }
   };
@@ -14336,14 +14336,14 @@ function readSubscriptions(absManifestPath) {
 }
 function checkPluginTerraform(root) {
   const violations = [];
-  const coreManifest = existsSync53(join64(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
+  const coreManifest = existsSync52(join63(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
   for (const manifest of findPluginManifests(root)) {
     if (coreManifest && !isTemplateOwned(manifest, coreManifest)) continue;
-    const absManifest = join64(root, manifest);
+    const absManifest = join63(root, manifest);
     const subscriptions = readSubscriptions(absManifest);
     if (subscriptions === null) continue;
     const pluginDir2 = dirname10(absManifest);
-    if (existsSync53(join64(pluginDir2, "terraform"))) continue;
+    if (existsSync52(join63(pluginDir2, "terraform"))) continue;
     const relPluginDir = relative10(root, pluginDir2).split(sep4).join("/");
     violations.push({
       manifest,
@@ -14374,12 +14374,12 @@ async function runPluginTerraformCheck() {
 }
 
 // src/scripts/check-plugin-tool-supply.ts
-import { existsSync as existsSync55 } from "fs";
-import { join as join66 } from "path";
+import { existsSync as existsSync54 } from "fs";
+import { join as join65 } from "path";
 
 // src/lib/plugin-tool-supply-audit.ts
-import { existsSync as existsSync54, readFileSync as readFileSync43, readdirSync as readdirSync26, statSync as statSync16 } from "fs";
-import { join as join65 } from "path";
+import { existsSync as existsSync53, readFileSync as readFileSync43, readdirSync as readdirSync26, statSync as statSync16 } from "fs";
+import { join as join64 } from "path";
 
 // src/lib/openrouter-model-snapshot.ts
 var OPENROUTER_MODEL_SNAPSHOT_FETCHED_AT = "2026-08-10T06:39:01Z";
@@ -14796,7 +14796,7 @@ function listDirs(root) {
   }
   return entries.filter((e) => {
     try {
-      return statSync16(join65(root, e)).isDirectory();
+      return statSync16(join64(root, e)).isDirectory();
     } catch {
       return false;
     }
@@ -14812,7 +14812,7 @@ function walkFiles2(root, accept, skipDir) {
       return;
     }
     for (const entry of entries) {
-      const p = join65(dir, entry);
+      const p = join64(dir, entry);
       let st;
       try {
         st = statSync16(p);
@@ -14838,14 +14838,14 @@ function pluginPythonFiles(pluginDir2) {
   );
 }
 function pluginTerraformFiles(pluginDir2) {
-  const tfDir = join65(pluginDir2, "terraform");
+  const tfDir = join64(pluginDir2, "terraform");
   let entries;
   try {
     entries = readdirSync26(tfDir);
   } catch {
     return [];
   }
-  return entries.filter((e) => e.endsWith(".tf")).map((e) => join65(tfDir, e)).sort();
+  return entries.filter((e) => e.endsWith(".tf")).map((e) => join64(tfDir, e)).sort();
 }
 function extractManifestTools(manifestText) {
   let parsed;
@@ -15097,8 +15097,8 @@ function isSnapshotStale(fetchedAt, now) {
 function normalizeModelId(id) {
   return id.endsWith(":online") ? id.slice(0, -":online".length) : id;
 }
-var CONFIG_PY_PATH = join65("services", "api", "src", "api", "config.py");
-var ORCHESTRATION_SCHEMA_PATH = join65(
+var CONFIG_PY_PATH = join64("services", "api", "src", "api", "config.py");
+var ORCHESTRATION_SCHEMA_PATH = join64(
   "services",
   "api",
   "src",
@@ -15110,10 +15110,10 @@ function auditDeclaredModelIds(repoRoot, options = {}) {
   const knownModelIds = options.knownModelIds ?? OPENROUTER_MODEL_IDS;
   const snapshotFetchedAt = options.snapshotFetchedAt ?? OPENROUTER_MODEL_SNAPSHOT_FETCHED_AT;
   const now = options.now ?? /* @__PURE__ */ new Date();
-  const configPath = join65(repoRoot, CONFIG_PY_PATH);
-  const orchestrationPath = join65(repoRoot, ORCHESTRATION_SCHEMA_PATH);
-  const configMissing = !existsSync54(configPath);
-  const orchestrationSchemaMissing = !existsSync54(orchestrationPath);
+  const configPath = join64(repoRoot, CONFIG_PY_PATH);
+  const orchestrationPath = join64(repoRoot, ORCHESTRATION_SCHEMA_PATH);
+  const configMissing = !existsSync53(configPath);
+  const orchestrationSchemaMissing = !existsSync53(orchestrationPath);
   const knownSet = new Set(knownModelIds);
   const snapshotEmpty = knownModelIds.length === 0;
   const snapshotStale = isSnapshotStale(snapshotFetchedAt, now);
@@ -15184,7 +15184,7 @@ function auditDeclaredModelIds(repoRoot, options = {}) {
 function discoverPluginDirs(pluginsRoot) {
   return listDirs(pluginsRoot).filter((name) => {
     try {
-      return statSync16(join65(pluginsRoot, name, "biffo.plugin.json")).isFile();
+      return statSync16(join64(pluginsRoot, name, "biffo.plugin.json")).isFile();
     } catch {
       return false;
     }
@@ -15197,8 +15197,8 @@ function auditPluginToolSupply(pluginsRoot) {
   let terraformBlind = false;
   let totalDeclaredTools = 0;
   for (const name of pluginNames) {
-    const pluginDir2 = join65(pluginsRoot, name);
-    const manifestText = readFileSync43(join65(pluginDir2, "biffo.plugin.json"), "utf8");
+    const pluginDir2 = join64(pluginsRoot, name);
+    const manifestText = readFileSync43(join64(pluginDir2, "biffo.plugin.json"), "utf8");
     const manifest = extractManifestTools(manifestText);
     if (manifest.parseError) {
       findings.push({
@@ -15296,7 +15296,7 @@ function auditPluginToolSupply(pluginsRoot) {
         requiredEnvVars: envResult.envVars,
         missingEnvVars: anyWired ? [] : envResult.envVars,
         status: anyWired ? "ok" : "missing-env",
-        detail: anyWired ? `${entry.predicate}() is satisfiable: at least one of ${JSON.stringify(envResult.envVars)} is wired in Terraform` : `${entry.predicate}() reads ${JSON.stringify(envResult.envVars)} \u2014 NONE of these are wired by any environment_variables block under ${join65(pluginDir2, "terraform")}, so this deployment can never supply it`
+        detail: anyWired ? `${entry.predicate}() is satisfiable: at least one of ${JSON.stringify(envResult.envVars)} is wired in Terraform` : `${entry.predicate}() reads ${JSON.stringify(envResult.envVars)} \u2014 NONE of these are wired by any environment_variables block under ${join64(pluginDir2, "terraform")}, so this deployment can never supply it`
       });
     }
   }
@@ -15328,9 +15328,16 @@ function auditPluginToolSupply(pluginsRoot) {
 // src/scripts/check-plugin-tool-supply.ts
 async function runPluginToolSupplyCheck() {
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  const ownership = classifyRepoOwnership(root);
+  if (ownership === "satellite") {
+    console.log(
+      "\u2713 plugin tool-supply guard: skipped \u2014 this repo is not the template or an instance, so it holds no services/_plugins/ tool grants and no services/api/ model-id catalogue to audit (a sibling/plugin repo may carry an unrelated services/api/ of its own \u2014 a BFF, not the ADR-0002 Core API this guard checks)."
+    );
+    return;
+  }
   let allOk = true;
-  const pluginsRoot = join66(root, "services", "_plugins");
-  if (!existsSync55(pluginsRoot)) {
+  const pluginsRoot = join65(root, "services", "_plugins");
+  if (!existsSync54(pluginsRoot)) {
     console.log("\u2713 plugin tool-supply guard: no services/_plugins/ \u2014 nothing to audit");
   } else {
     const report = auditPluginToolSupply(pluginsRoot);
@@ -15360,8 +15367,8 @@ async function runPluginToolSupplyCheck() {
       console.log(`\u2713 plugin tool-supply guard: ${report.summary}`);
     }
   }
-  const servicesApiRoot = join66(root, "services", "api");
-  if (!existsSync55(servicesApiRoot)) {
+  const servicesApiRoot = join65(root, "services", "api");
+  if (!existsSync54(servicesApiRoot)) {
     console.log("\u2713 plugin model-id guard: no services/api/ \u2014 nothing to audit");
   } else {
     const modelReport = auditDeclaredModelIds(root);
@@ -15738,12 +15745,12 @@ async function runSharedFileReductionCheck(args) {
 }
 
 // src/scripts/check-skeleton-drift.ts
-import { existsSync as existsSync56, readdirSync as readdirSync28 } from "fs";
-import { join as join68 } from "path";
+import { existsSync as existsSync55, readdirSync as readdirSync28 } from "fs";
+import { join as join67 } from "path";
 
 // src/lib/skeleton-drift-guard.ts
 import { readFileSync as readFileSync46, readdirSync as readdirSync27, statSync as statSync17 } from "fs";
-import { join as join67 } from "path";
+import { join as join66 } from "path";
 var isWorkflow = (rel) => rel.startsWith(".github/workflows/") && (rel.endsWith(".yml") || rel.endsWith(".yaml"));
 var isRootLayout = (rel) => rel.endsWith("src/app/layout.tsx");
 var uncommented = (contents) => contents.split("\n").filter((line) => !/^\s*(\/\/|\/\*|\*)/.test(line)).join("\n");
@@ -15807,7 +15814,7 @@ function walk(dir, base = dir) {
   }
   for (const entry of entries) {
     if (entry === ".venv" || entry === "node_modules" || entry === ".git") continue;
-    const abs = join67(dir, entry);
+    const abs = join66(dir, entry);
     let isDir;
     try {
       isDir = statSync17(abs).isDirectory();
@@ -15829,7 +15836,7 @@ function auditSkeleton(skeletonRoot, name, rules = SKELETON_RULES) {
       if (!rule.appliesTo(rel)) continue;
       let contents;
       try {
-        contents = readFileSync46(join67(skeletonRoot, rel), "utf8");
+        contents = readFileSync46(join66(skeletonRoot, rel), "utf8");
       } catch {
         continue;
       }
@@ -15858,23 +15865,23 @@ function formatViolations2(violations) {
 
 // src/scripts/check-skeleton-drift.ts
 function discoverSkeletons(root) {
-  const skeletonsDir = join68(root, "_skeletons");
+  const skeletonsDir = join67(root, "_skeletons");
   let entries;
   try {
     entries = readdirSync28(skeletonsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
   } catch {
     return [];
   }
-  return entries.filter((name) => existsSync56(join68(skeletonsDir, name, ".github", "workflows", "ci.yml"))).sort();
+  return entries.filter((name) => existsSync55(join67(skeletonsDir, name, ".github", "workflows", "ci.yml"))).sort();
 }
 async function runSkeletonDriftCheck() {
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
   const skeletons = discoverSkeletons(root);
   let filesConsidered = 0;
   for (const name of skeletons) {
-    const skeletonRoot = join68(root, "_skeletons", name);
+    const skeletonRoot = join67(root, "_skeletons", name);
     filesConsidered += findWorkflowFiles(skeletonRoot).length;
-    if (existsSync56(join68(skeletonRoot, "apps", "frontend", "src", "app", "layout.tsx"))) {
+    if (existsSync55(join67(skeletonRoot, "apps", "frontend", "src", "app", "layout.tsx"))) {
       filesConsidered += 1;
     }
   }
@@ -15882,7 +15889,7 @@ async function runSkeletonDriftCheck() {
     `audited ${skeletons.length} skeleton(s) (${skeletons.join(", ") || "none"}), ${filesConsidered} file(s) considered, under ${root}/_skeletons`
   );
   if (skeletons.length === 0) {
-    if (!existsSync56(join68(root, "_skeletons"))) {
+    if (!existsSync55(join67(root, "_skeletons"))) {
       console.log(
         `\xB7 Skeleton-drift guard: no _skeletons/ directory under ${root} \u2014 this is not a repo that ships scaffolding (a satellite repo never carries one). Not applicable; skipping.`
       );
@@ -15894,7 +15901,7 @@ async function runSkeletonDriftCheck() {
     process.exit(1);
   }
   const violations = skeletons.flatMap(
-    (name) => auditSkeleton(join68(root, "_skeletons", name), name)
+    (name) => auditSkeleton(join67(root, "_skeletons", name), name)
   );
   if (violations.length > 0) {
     console.error("\u2717 Skeleton-drift guard: drift found between this repo and its scaffolding\n");
@@ -16095,8 +16102,8 @@ function rawArgsAfter(subcommand) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync57, readFileSync as readFileSync47 } from "fs";
-import { join as join69, resolve as resolve20 } from "path";
+import { existsSync as existsSync56, readFileSync as readFileSync47 } from "fs";
+import { join as join68, resolve as resolve20 } from "path";
 import chalk21 from "chalk";
 import { Command as Command25 } from "commander";
 
@@ -16517,8 +16524,8 @@ async function runDoctorFixBranches(cwd, facts, deps = { git: new GitAdapter(),
   );
 }
 function readLocalCoreVersion(cwd) {
-  const path = join69(cwd, INSTANCE_CORE_FILE);
-  if (!existsSync57(path)) return null;
+  const path = join68(cwd, INSTANCE_CORE_FILE);
+  if (!existsSync56(path)) return null;
   try {
     return extractVersionField(readFileSync47(path, "utf8"));
   } catch {
@@ -16540,8 +16547,8 @@ function extractVersionField(contents) {
   return match?.[1] ?? null;
 }
 function readFossil(cwd) {
-  const path = join69(cwd, CORE_VERSION_FILE);
-  if (!existsSync57(path)) return null;
+  const path = join68(cwd, CORE_VERSION_FILE);
+  if (!existsSync56(path)) return null;
   try {
     const value = readFileSync47(path, "utf8").trim();
     return value === "" ? null : value;
@@ -17080,13 +17087,13 @@ import { fileURLToPath as fileURLToPath6 } from "url";
 import { Command as Command27 } from "commander";
 
 // src/lib/packaged-scripts.ts
-import { existsSync as existsSync58 } from "fs";
-import { dirname as dirname11, join as join70 } from "path";
+import { existsSync as existsSync57 } from "fs";
+import { dirname as dirname11, join as join69 } from "path";
 function findPackagedScript(startDir, relativePath) {
   let dir = startDir;
   for (; ; ) {
-    const candidate = join70(dir, relativePath);
-    if (existsSync58(candidate)) return candidate;
+    const candidate = join69(dir, relativePath);
+    if (existsSync57(candidate)) return candidate;
     const parent = dirname11(dir);
     if (parent === dir) return null;
     dir = parent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.309.3",
+  "version": "0.310.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",

package/scripts/verify.sh

@@ -1455,11 +1455,30 @@ if [ -f scripts/biffo.sh ]; then
   # biffo.core.json's own version and compares against it -- but this repo
   # never carries biffo.core.json (it is the template, not an instance), so
   # the script itself detects that and exits 0 as a genuine skip (see its own
-  # doc comment) rather than attempting a comparison it has no tree for. Kept
-  # unconditional, exactly like the line above, for the same reason: ci.yml's
-  # exact command text must appear in `verify.sh --list`'s output or the
-  # parity test (verify-parity.test.ts, #1773) reports it uncategorised.
-  run_check orphan-ratchet-instance sh scripts/check-orphan-ratchet-instance.sh
+  # doc comment) rather than attempting a comparison it has no tree for.
+  #
+  # Guarded with `[ -f ... ] &&`, unlike the line above, because this script
+  # is a raw file path rather than a `scripts/biffo.sh check <name>` call
+  # through the versioned CLI bridge -- every other check in this block goes
+  # through that bridge, which resolves against the pinned, PACKAGED CLI and
+  # so works from any repo. This one does not, and `scripts/
+  # check-orphan-ratchet-instance.sh` is template-owned but never packaged
+  # for a satellite: not in shared-files.json's `files` (never copied to a
+  # sibling/plugin repo) and not in `PACKAGED_ROOT_ASSETS` (never bundled
+  # into the npm tarball) -- it only ever reaches a real INSTANCE, via
+  # `biffo core upgrade`'s ordinary three-way merge. A satellite running the
+  # packaged `verify.sh` through `scripts/biffo.sh verify` therefore had no
+  # such file on disk at all, and a bare `sh scripts/
+  # check-orphan-ratchet-instance.sh` failed at the shell -- "cannot open
+  # ... No such file" -- before the script's own biffo.core.json skip ever
+  # got a chance to run (biffo-template#1943). The guard is true in every
+  # checkout that actually carries the file (this repo, and any instance
+  # that has upgraded far enough to have received it), so `verify.sh --list`'s
+  # output here is unchanged and parity with ci.yml's own unconditional step
+  # holds exactly as before; it is false only in a satellite, where this now
+  # skips instead of crashing the rest of the gate.
+  [ -f scripts/check-orphan-ratchet-instance.sh ] &&
+    run_check orphan-ratchet-instance sh scripts/check-orphan-ratchet-instance.sh
   run_check cognito-invite sh scripts/biffo.sh check cognito-invite-template
   run_check lambda-output sh scripts/biffo.sh check lambda-output
   run_check pipe-trap sh scripts/biffo.sh check pipe-trap