@biffo/cli 0.303.2 → 0.303.4

package/_skeletons/plugin-template/README.md

@@ -137,7 +137,7 @@ repository with its own independent `uv sync` / `uv.lock`, not inside
 biffo-template's workspace. Once copied out, `uv sync && uv run pytest`
 works standalone with no dependency on the rest of biffo-template.
 
-## The `biffo-plugin-sdk` dependency: PyPI pin, pending the first release
+## The `biffo-plugin-sdk` dependency: PyPI pin
 
 `pyproject.toml` declares:
 
@@ -148,41 +148,30 @@ dependencies = [
 ]
 ```
 
-This is a **PyPI-style version pin**, and it is the correct end state: the
-SDK is versioned `1.0.0` and biffo-template's
+This is a **PyPI-style version pin**: the SDK is published via
+biffo-template's
 [`.github/workflows/publish-sdk.yml`](https://github.com/keiranholloway/biffo-template/blob/main/.github/workflows/publish-sdk.yml)
-builds and publishes it to PyPI (via Trusted Publishing) on a pushed
-`sdk-v*` tag. `>=1.0,<2.0` matches the `"biffo-plugin-sdk": "^1.0"` that
+(Trusted Publishing) on a pushed `sdk-v*` tag, and the first release has
+already happened — this skeleton's own `uv.lock` resolves `biffo-plugin-sdk`
+1.4.0 from `https://pypi.org/simple` (see its `biffo-plugin-sdk` entry).
+`>=1.0,<2.0` matches the `"biffo-plugin-sdk": "^1.0"` that
 `biffo.plugin.json` declares, and the SDK carries its own independent
 semver — it is **not** tied to the template's core version, so a major
 bump here means the plugin API broke and nothing else.
 
-**Ordering caveat.** The release _pipeline_ exists; the _release_ does not
-yet. `biffo-plugin-sdk` has never been uploaded — the PyPI project is
-unregistered until the owner configures the Trusted Publisher and pushes
-`sdk-v1.0.0`. Until that happens, `uv sync` in a freshly-copied plugin repo
-still cannot resolve this dependency, and you need one of the two local
-overrides below. Once 1.0.0 is live, **delete the override** — the
-`dependencies` entry above already points at the real thing.
-
-Two ways to make local development work before that happens:
-
-1. **Path dependency** (if developing inside a biffo-template checkout,
-   e.g. for a plugin you plan to upstream into `services/`): add
-   ```toml
-   [tool.uv.sources]
-   biffo-plugin-sdk = { path = "../../packages/python-sdk", editable = true }
-   ```
-2. **Git dependency** (developing this plugin as a genuinely separate repo
-   against an unpublished SDK):
-   ```toml
-   [tool.uv.sources]
-   biffo-plugin-sdk = { git = "https://github.com/keiranholloway/biffo-template", subdirectory = "packages/python-sdk" }
-   ```
-
-Either override goes in `[tool.uv.sources]` only — the PyPI-style
-`dependencies` entry above stays as-is, so removing the override is the
-only change needed once the SDK actually ships to PyPI.
+`uv sync` in a freshly-copied plugin repo resolves this pin normally; no
+`[tool.uv.sources]` override is needed. If you are developing this plugin
+*inside* a `biffo-template` checkout (e.g. one you plan to upstream into
+`services/`) and want to iterate against an unreleased SDK change before it
+ships, a local override still works:
+
+```toml
+[tool.uv.sources]
+biffo-plugin-sdk = { path = "../../packages/python-sdk", editable = true }
+```
+
+Keep it local (uncommitted, or removed before committing) — the PyPI-style
+`dependencies` entry above is what every scaffolded plugin repo ships with.
 
 ## Manifest validation: why CI doesn't hard-gate on `registry-schema.json`
 

package/_skeletons/plugin-template/pyproject.toml

@@ -4,22 +4,14 @@ version = "0.1.0"
 description = "Example Biffo plugin — replace this with your own plugin's name and description"
 requires-python = ">=3.13"
 dependencies = [
-  # biffo-plugin-sdk has a real release path as of biffo-template's
-  # .github/workflows/publish-sdk.yml: the package is versioned 1.0.0 and
-  # publishes to PyPI (via Trusted Publishing) when an `sdk-v*` tag is
-  # pushed. This pin is therefore the *correct end state* and is left as-is.
-  #
-  # ORDERING: the pin only resolves once the owner has actually pushed
-  # `sdk-v1.0.0` and PyPI has the release. Until that first publish,
-  # `uv sync` in a freshly-copied plugin repo cannot resolve it — the same
-  # as before this comment was written, so nothing regressed here; what
-  # changed is that the fix is now one tag push away rather than unbuilt.
-  # Deliberately NOT worked around with a git/path source in the committed
-  # file: baking one in would mean every plugin repo forked from this
-  # skeleton silently keeps building against a moving git ref long after
-  # the real release exists. Use a local `[tool.uv.sources]` override until
-  # then — see the README's "biffo-plugin-sdk dependency" section, which
-  # documents both options and says which to delete once 1.0.0 is live.
+  # biffo-plugin-sdk has a real release path via biffo-template's
+  # .github/workflows/publish-sdk.yml: it publishes to PyPI (via Trusted
+  # Publishing) when an `sdk-v*` tag is pushed. That first publish has
+  # already happened — this skeleton's own uv.lock resolves biffo-plugin-sdk
+  # 1.4.0 from https://pypi.org/simple (see uv.lock's own `biffo-plugin-sdk`
+  # entry) — so `uv sync` in a freshly-copied plugin repo resolves this pin
+  # normally, with no `[tool.uv.sources]` override needed (biffo-template#1769
+  # side finding).
   "biffo-plugin-sdk>=1.0,<2.0",
   "aws-lambda-powertools[tracer]>=3.4.0",
   "httpx>=0.28.1",

package/dist/index.js

@@ -8273,7 +8273,8 @@ import {
 import { dirname as dirname7, join as join26 } from "path";
 var STANDALONE_ONLY_ENTRIES = {
   ".github": "standalone-repo CI/release workflows \u2014 the host monorepo already runs lint/type/test/security over services/",
-  "registry-schema.json": "the plugin-registry publishing schema, used when submitting a *published* plugin to the registry repo, not by an in-tree plugin"
+  "registry-schema.json": "the plugin-registry publishing schema, used when submitting a *published* plugin to the registry repo, not by an in-tree plugin",
+  "uv.lock": "a standalone repo's own lockfile, substituted like any other text file (issue #1769) \u2014 a nested lock inside a monorepo's services/ would be wrong there, since the host resolves its own dependency tree"
 };
 var NEVER_COPY = /* @__PURE__ */ new Set([
   ".git",
@@ -8284,7 +8285,6 @@ var NEVER_COPY = /* @__PURE__ */ new Set([
   ".pytest_cache",
   ".mypy_cache",
   "dist",
-  "uv.lock",
   ".DS_Store"
 ]);
 var PLUGIN_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
@@ -8537,6 +8537,11 @@ async function runStandaloneCreate(names, options, deps) {
 `
   );
   if (options.commit) {
+    if (!existsSync27(join27(destDir, "uv.lock"))) {
+      throw new Error(
+        `Scaffolded plugin at ${destDir} has no uv.lock. The standalone layout must carry a substituted uv.lock (see plugin-scaffold.ts STANDALONE_ONLY_ENTRIES) so the first commit's CI run can satisfy 'uv sync --locked'. Refusing to commit a repo that would ship red on its very first push (issue #1769) \u2014 run 'uv lock' in ${destDir} first.`
+      );
+    }
     await deps.git.init(destDir);
     await deps.git.add(destDir, ["."]);
     await deps.git.commit(destDir, `feat: scaffold ${names.slug} plugin`);
@@ -11122,8 +11127,15 @@ async function runApiGatewayIntegrationCheck() {
   try {
     report = auditApiGatewayIntegrations(root);
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("no .tf files found under")) {
+      console.log(
+        `\xB7 API Gateway integration-qualifier guard: not applicable \u2014 ${message} This repo carries no Terraform at all, which is expected for a non-instance satellite. Skipping.`
+      );
+      return;
+    }
     console.error("\u2717 API Gateway integration-qualifier guard: could not run\n");
-    console.error(err instanceof Error ? err.message : String(err));
+    console.error(message);
     process.exit(1);
   }
   console.log(`scanned ${report.filesScanned} .tf file(s) under ${root}`);
@@ -11653,6 +11665,10 @@ async function runCodeqlSuppressionCheck() {
   console.log("\u2713 codeql-suppression guard: no dead `codeql[...]` suppression comment found");
 }
 
+// src/scripts/check-cognito-invite-template.ts
+import { existsSync as existsSync42 } from "fs";
+import { join as join46 } from "path";
+
 // src/lib/cognito-invite-template-guard.ts
 import { readdirSync as readdirSync19, readFileSync as readFileSync33, statSync as statSync11 } from "fs";
 import { join as join45 } from "path";
@@ -11769,6 +11785,12 @@ async function runCognitoInviteTemplateCheck() {
   const files = findModuleTerraformFiles(root);
   console.log(`audited ${files.length} .tf file(s) under modules/ under ${root}`);
   if (files.length === 0) {
+    if (!existsSync42(join46(root, "modules"))) {
+      console.log(
+        `\xB7 Cognito invite template guard: not applicable \u2014 no modules/ directory under ${root} \u2014 this is not a template/instance tree (a satellite repo never carries the template-owned Terraform modules). Skipping.`
+      );
+      return;
+    }
     console.error(
       "\u2717 Cognito invite template guard: found 0 .tf files under modules/ \u2014 this looks like a broken scan, not a clean repo. Refusing to report success over zero input."
     );
@@ -11787,11 +11809,11 @@ async function runCognitoInviteTemplateCheck() {
 }
 
 // src/scripts/check-core-direct-paths.ts
-import { join as join47 } from "path";
+import { join as join48 } from "path";
 
 // src/lib/core-direct-paths-audit.ts
-import { existsSync as existsSync42, readFileSync as readFileSync34, readdirSync as readdirSync20, statSync as statSync12 } from "fs";
-import { join as join46 } from "path";
+import { existsSync as existsSync43, readFileSync as readFileSync34, readdirSync as readdirSync20, statSync as statSync12 } from "fs";
+import { join as join47 } from "path";
 var EXTERNAL_BASE_IDENTIFIERS = ["CORE_API_URL"];
 var API_ROUTE_PREFIX = "/api/v1";
 var TEST_FILE_SUFFIXES = [".test.ts", ".test.tsx", ".spec.ts", ".spec.tsx"];
@@ -11955,7 +11977,7 @@ function walkFiles(root, accept, skipDir) {
       return;
     }
     for (const entry of entries) {
-      const p = join46(dir, entry);
+      const p = join47(dir, entry);
       let st;
       try {
         st = statSync12(p);
@@ -12050,7 +12072,7 @@ function pathMatchesAnyCorePrefix(normalized, corePrefixes, apiRoutePrefix = API
 }
 function resolveSiblingCoreSrc(params) {
   const { estateDir, sibling } = params;
-  const configPath = join46(estateDir, sibling, "biffo.sibling.json");
+  const configPath = join47(estateDir, sibling, "biffo.sibling.json");
   let raw;
   try {
     raw = readFileSync34(configPath, "utf8");
@@ -12073,8 +12095,8 @@ function resolveSiblingCoreSrc(params) {
       `cannot resolve ${sibling}'s core: ${configPath} has no non-empty "core_project" field.`
     );
   }
-  const coreApiSrcDir = join46(estateDir, coreProject, "services", "api", "src");
-  if (!existsSync42(coreApiSrcDir)) {
+  const coreApiSrcDir = join47(estateDir, coreProject, "services", "api", "src");
+  if (!existsSync43(coreApiSrcDir)) {
     throw new Error(
       `cannot resolve ${sibling}'s core: biffo.sibling.json names core_project "${coreProject}", but ${coreApiSrcDir} does not exist -- the instance is missing from this estate checkout, not merely unmatched. Refusing to silently skip ${sibling} and shrink the audit's denominator.`
     );
@@ -12117,7 +12139,7 @@ function auditSiblingCoreDirectPaths(params) {
 async function runCoreDirectPathsCheck(opts = {}) {
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
   const sibling = opts.sibling ?? "sibling-template (self-check)";
-  const frontendSrcDir = opts.frontendSrc ?? join47(root, "_skeletons", "sibling-template", "apps", "frontend", "src");
+  const frontendSrcDir = opts.frontendSrc ?? join48(root, "_skeletons", "sibling-template", "apps", "frontend", "src");
   let coreApiSrcDir;
   let coreProject = null;
   if (opts.coreSrc) {
@@ -12133,7 +12155,7 @@ async function runCoreDirectPathsCheck(opts = {}) {
     coreApiSrcDir = resolution.coreApiSrcDir;
     coreProject = resolution.coreProject;
   } else {
-    coreApiSrcDir = join47(root, "services", "api", "src");
+    coreApiSrcDir = join48(root, "services", "api", "src");
   }
   const report = auditSiblingCoreDirectPaths({ sibling, frontendSrcDir, coreApiSrcDir });
   console.log(
@@ -12198,8 +12220,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: readFileSync47, existsSync: existsSync57 } = await import("fs");
-      if (existsSync57(messageFile)) commitMessage = readFileSync47(messageFile, "utf8");
+      const { readFileSync: readFileSync47, existsSync: existsSync59 } = await import("fs");
+      if (existsSync59(messageFile)) commitMessage = readFileSync47(messageFile, "utf8");
     }
   } else {
     const base = process.env["GITHUB_BASE_REF"] ?? args[0];
@@ -12300,16 +12322,16 @@ ${BOLD}If the divergence is deliberate${OFF}
 }
 
 // src/scripts/check-distribution-inventory.ts
-import { existsSync as existsSync44 } from "fs";
-import { join as join49 } from "path";
+import { existsSync as existsSync45 } from "fs";
+import { join as join50 } from "path";
 
 // src/lib/distribution-inventory.ts
-import { existsSync as existsSync43, readFileSync as readFileSync35 } from "fs";
-import { join as join48 } from "path";
+import { existsSync as existsSync44, readFileSync as readFileSync35 } from "fs";
+import { join as join49 } from "path";
 var INVENTORY_FILENAME = "distribution-inventory.json";
 function loadDistributionInventory(root) {
-  const path = join48(root, INVENTORY_FILENAME);
-  if (!existsSync43(path)) {
+  const path = join49(root, INVENTORY_FILENAME);
+  if (!existsSync44(path)) {
     throw new Error(
       `${INVENTORY_FILENAME} not found at ${root} -- expected it beside core-manifest.json`
     );
@@ -12474,7 +12496,7 @@ async function runDistributionInventoryCheck(root) {
     );
     return;
   }
-  if (!existsSync44(join49(repoRoot, INVENTORY_FILENAME))) {
+  if (!existsSync45(join50(repoRoot, INVENTORY_FILENAME))) {
     console.log(
       `\u2713 distribution-inventory: skipped \u2014 no ${INVENTORY_FILENAME} at ${repoRoot}. This is a template-only registry; a checkout that legitimately has none has nothing for this guard to check.`
     );
@@ -12500,7 +12522,7 @@ async function runDistributionInventoryCheck(root) {
 }
 
 // src/scripts/check-distribution-remote-state.ts
-import { join as join50 } from "path";
+import { join as join51 } from "path";
 async function ghExecCommand(file, args) {
   const result = await execa(file, args, { reject: false });
   return { stdout: String(result.stdout ?? ""), exitCode: result.exitCode ?? null };
@@ -12515,7 +12537,7 @@ async function runDistributionRemoteStateCheck(root) {
     }
   }
   console.log(
-    `distribution-remote-state: examined ${assertions.length} remote content assertion(s) declared across ${inventory.entries.length} inventory entries (${join50(repoRoot, "distribution-inventory.json")})`
+    `distribution-remote-state: examined ${assertions.length} remote content assertion(s) declared across ${inventory.entries.length} inventory entries (${join51(repoRoot, "distribution-inventory.json")})`
   );
   if (assertions.length === 0) {
     console.log("\u2713 distribution-remote-state: nothing declared to check");
@@ -12561,7 +12583,7 @@ ${assertion.ref}`;
 
 // src/lib/eventbridge-log-permission-guard.ts
 import { readFileSync as readFileSync36, readdirSync as readdirSync21, statSync as statSync13 } from "fs";
-import { join as join51 } from "path";
+import { join as join52 } from "path";
 var SKIP_DIRS3 = /* @__PURE__ */ new Set(["node_modules", ".git", ".terraform", ".worktrees", "dist"]);
 var EVENT_TARGET_TYPE = "aws_cloudwatch_event_target";
 var LOG_RESOURCE_POLICY_TYPE = "aws_cloudwatch_log_resource_policy";
@@ -12638,7 +12660,7 @@ function walkTerraformFiles2(root) {
       return;
     }
     for (const entry of entries) {
-      const p = join51(dir, entry);
+      const p = join52(dir, entry);
       let st;
       try {
         st = statSync13(p);
@@ -12739,8 +12761,15 @@ async function runEventBridgeLogPermissionCheck() {
   try {
     report = auditEventBridgeLogPermissions(root);
   } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("no .tf files found under")) {
+      console.log(
+        `\xB7 EventBridge log permission guard: not applicable \u2014 ${message} This repo carries no Terraform at all, which is expected for a non-instance satellite. Skipping.`
+      );
+      return;
+    }
     console.error("\u2717 EventBridge log permission guard: could not run\n");
-    console.error(err instanceof Error ? err.message : String(err));
+    console.error(message);
     process.exit(1);
   }
   console.log(`audited ${report.filesScanned} .tf file(s) under ${root}`);
@@ -12771,8 +12800,8 @@ async function runEventBridgeLogPermissionCheck() {
 }
 
 // src/scripts/check-instance-adoption.ts
-import { existsSync as existsSync45 } from "fs";
-import { join as join52 } from "path";
+import { existsSync as existsSync46 } from "fs";
+import { join as join53 } from "path";
 async function runInstanceAdoptionCheck(opts = {}) {
   if (!opts.instanceDir) {
     console.error(
@@ -12780,7 +12809,7 @@ async function runInstanceAdoptionCheck(opts = {}) {
     );
     process.exit(2);
   }
-  if (!existsSync45(opts.instanceDir)) {
+  if (!existsSync46(opts.instanceDir)) {
     console.error(
       `\u2717 instance-adoption guard: --instance-dir ${opts.instanceDir} does not exist \u2014 cannot tell whether it is adopted, and that is not the same as a clean pass.`
     );
@@ -12788,7 +12817,7 @@ async function runInstanceAdoptionCheck(opts = {}) {
   }
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
   const theirsDir = opts.theirsDir ?? root;
-  const instanceLabel = opts.instance ?? join52(opts.instanceDir).split("/").filter(Boolean).pop();
+  const instanceLabel = opts.instance ?? join53(opts.instanceDir).split("/").filter(Boolean).pop();
   const report = checkInstanceAdoption(theirsDir, opts.instanceDir);
   console.log(
     `examined ${report.examinedInstances} instance (${instanceLabel}) against ${report.registeredPairs} registered pair(s), ${report.applicablePairs} applicable to this instance, against template tree ${theirsDir}`
@@ -12811,11 +12840,11 @@ async function runInstanceAdoptionCheck(opts = {}) {
 
 // src/lib/lambda-output-guard.ts
 import { readFileSync as readFileSync38 } from "fs";
-import { join as join54 } from "path";
+import { join as join55 } from "path";
 
 // src/lib/terraform-input-guard.ts
-import { existsSync as existsSync46, readdirSync as readdirSync22, readFileSync as readFileSync37, statSync as statSync14 } from "fs";
-import { join as join53 } from "path";
+import { existsSync as existsSync47, readdirSync as readdirSync22, readFileSync as readFileSync37, statSync as statSync14 } from "fs";
+import { join as join54 } from "path";
 var GUARDED_SUBCOMMANDS = [
   "init",
   "plan",
@@ -12829,7 +12858,7 @@ function stripComments2(source) {
   return source.split("\n").map((line) => line.replace(/(^|\s)#.*$/, "$1")).join("\n");
 }
 function vendoredPluginServiceDirs(repoRoot) {
-  const servicesDir = join53(repoRoot, "services");
+  const servicesDir = join54(repoRoot, "services");
   const result = /* @__PURE__ */ new Set();
   let entries;
   try {
@@ -12838,9 +12867,9 @@ function vendoredPluginServiceDirs(repoRoot) {
     return result;
   }
   for (const entry of entries) {
-    const full = join53(servicesDir, entry);
-    if (!existsSync46(full) || !statSync14(full).isDirectory()) continue;
-    if (existsSync46(join53(full, "biffo.plugin.json"))) {
+    const full = join54(servicesDir, entry);
+    if (!existsSync47(full) || !statSync14(full).isDirectory()) continue;
+    if (existsSync47(join54(full, "biffo.plugin.json"))) {
       result.add(entry);
     }
   }
@@ -12862,7 +12891,7 @@ function findWorkflowFiles(repoRoot) {
       if (entry === ".github" && relative11.startsWith("services/") && vendoredPluginDirs.has(relative11.slice("services/".length))) {
         continue;
       }
-      const full = join53(dir, entry);
+      const full = join54(dir, entry);
       const rel = relative11 ? `${relative11}/${entry}` : entry;
       let isDir;
       try {
@@ -12912,7 +12941,7 @@ function checkWorkflowSource(file, rawSource) {
 }
 function checkTerraformInput(repoRoot) {
   return findWorkflowFiles(repoRoot).flatMap(
-    (file) => checkWorkflowSource(file, readFileSync37(join53(repoRoot, file), "utf8"))
+    (file) => checkWorkflowSource(file, readFileSync37(join54(repoRoot, file), "utf8"))
   );
 }
 
@@ -12970,7 +12999,7 @@ function checkWorkflowSource2(file, rawSource) {
 }
 function checkLambdaOutput(repoRoot) {
   return findWorkflowFiles(repoRoot).flatMap(
-    (file) => checkWorkflowSource2(file, readFileSync38(join54(repoRoot, file), "utf8"))
+    (file) => checkWorkflowSource2(file, readFileSync38(join55(repoRoot, file), "utf8"))
   );
 }
 
@@ -12998,8 +13027,8 @@ async function runLambdaOutputCheck() {
 }
 
 // src/scripts/check-migration-body-change.ts
-import { existsSync as existsSync47 } from "fs";
-import { join as join55 } from "path";
+import { existsSync as existsSync48 } from "fs";
+import { join as join56 } from "path";
 
 // src/lib/migration-body-change-guard.ts
 function checkMigrationBodyChangeMarkers(diffs) {
@@ -13065,7 +13094,7 @@ async function runMigrationBodyChangeCheck(argv) {
     );
     return;
   }
-  if (!existsSync47(join55(root, MIGRATIONS_VERSIONS_DIR))) {
+  if (!existsSync48(join56(root, MIGRATIONS_VERSIONS_DIR))) {
     console.log(`\u2713 migration body-change guard: no ${MIGRATIONS_VERSIONS_DIR} in this repo.`);
     return;
   }
@@ -13167,8 +13196,8 @@ ${BOLD2}What to do${OFF2}
 }
 
 // src/scripts/check-orphan-ratchet.ts
-import { existsSync as existsSync48 } from "fs";
-import { basename as basename3 } from "path";
+import { existsSync as existsSync49 } from "fs";
+import { basename as basename3, join as join57 } from "path";
 function reportOrphan(entry, manifest) {
   console.error(`  ${entry.path}`);
   const { templateOwnedMatch, nearestUserOwnedEntries } = explainOwnership(entry.path, manifest);
@@ -13190,7 +13219,7 @@ function reportOrphan(entry, manifest) {
   }
 }
 async function runOrphanRatchetCheck(opts = {}) {
-  if (opts.instanceDir !== void 0 && !existsSync48(opts.instanceDir)) {
+  if (opts.instanceDir !== void 0 && !existsSync49(opts.instanceDir)) {
     console.error(
       `\u2717 orphan-ratchet guard: --instance-dir ${opts.instanceDir} does not exist \u2014 cannot tell whether it carries unsanctioned files, and that is not the same as a clean pass.`
     );
@@ -13207,6 +13236,12 @@ async function runOrphanRatchetCheck(opts = {}) {
       "self-check mode: --instance-dir was not given, so it defaulted to --theirs-dir (this repo's own root) alongside --base-dir \u2014 all three trees are the same, so this run can only ever find zero orphans by construction. See this script's doc comment. Pass a real instance tree with --instance-dir for a check that can actually find something. biffo-template#1714."
     );
   }
+  if (!existsSync49(join57(theirsDir, CORE_MANIFEST_FILE))) {
+    console.log(
+      `orphan-ratchet guard (${label}): no ${CORE_MANIFEST_FILE} in ${theirsDir} \u2014 this is not a Biffo template/instance tree (a satellite repo never carries one), so there is no ownership manifest to classify paths against. Not applicable; skipping.`
+    );
+    return;
+  }
   const manifest = readCoreManifest(theirsDir);
   const plan = await planCoreUpgrade({ baseDir, oursDir: instanceDir, theirsDir, manifest });
   const baseline = readOrphanBaseline(instanceDir);
@@ -13233,7 +13268,7 @@ baseline was ${String(ratchet.baseline)}, now ${String(ratchet.count)}. See biff
 
 // src/scripts/check-pipe-trap.ts
 import { readFileSync as readFileSync39, readdirSync as readdirSync23 } from "fs";
-import { join as join56, relative as relative9 } from "path";
+import { join as join58, relative as relative9 } from "path";
 
 // src/lib/pipe-trap-guard.ts
 var STATUS_BEARING = [
@@ -13329,7 +13364,7 @@ function findPipeTraps(source) {
 function shellFiles(root) {
   const out = [];
   for (const dir of ["scripts", ".githooks"]) {
-    const full = join56(root, dir);
+    const full = join58(root, dir);
     let entries;
     try {
       entries = readdirSync23(full, { withFileTypes: true });
@@ -13339,7 +13374,7 @@ function shellFiles(root) {
     for (const entry of entries) {
       if (!entry.isFile()) continue;
       if (dir === "scripts" && !entry.name.endsWith(".sh")) continue;
-      out.push(join56(full, entry.name));
+      out.push(join58(full, entry.name));
     }
   }
   return out;
@@ -13371,9 +13406,13 @@ 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 join60 } from "path";
+
 // src/lib/plugin-allowlist-convention.ts
 import { readFileSync as readFileSync40 } from "fs";
-import { join as join57 } from "path";
+import { join as join59 } from "path";
 var COMPUTE_MAIN_TF = "modules/cloud/aws/compute/main.tf";
 var PLUGIN_TEMPLATE_MAIN_TF = "modules/plugins/_template/main.tf";
 var ALLOWLIST_MAIN_TF = "modules/cloud/aws/plugin-allowlist/main.tf";
@@ -13384,7 +13423,7 @@ var PLUGIN = "<plugin>";
 var ACCOUNT = "<account>";
 function read(repoRoot, relative11) {
   try {
-    return readFileSync40(join57(repoRoot, relative11), "utf8");
+    return readFileSync40(join59(repoRoot, relative11), "utf8");
   } catch {
     throw new Error(`plugin-allowlist drift guard: cannot read ${relative11}`);
   }
@@ -13479,8 +13518,21 @@ 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(join60(root, relative11)));
+  if (missing.length === REQUIRED_SOURCES.length) {
+    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.`
+    );
+    return;
+  }
   let violations;
   try {
     violations = checkAllowlistConvention(root);
@@ -13505,32 +13557,32 @@ async function runPluginAllowlistConventionCheck() {
 }
 
 // src/scripts/check-plugin-collisions.ts
-import { existsSync as existsSync50 } from "fs";
-import { join as join59 } from "path";
+import { existsSync as existsSync52 } from "fs";
+import { join as join62 } from "path";
 
 // src/lib/plugin-collision-guard.ts
-import { existsSync as existsSync49, readdirSync as readdirSync24, statSync as statSync15 } from "fs";
-import { join as join58 } from "path";
+import { existsSync as existsSync51, 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 (!existsSync49(dir)) return [];
+  if (!existsSync51(dir)) return [];
   return readdirSync24(dir).filter((entry) => {
     if (IGNORED_DIRS.has(entry) || entry.startsWith(".")) return false;
     try {
-      return statSync15(join58(dir, entry)).isDirectory();
+      return statSync15(join61(dir, entry)).isDirectory();
     } catch {
       return false;
     }
   });
 }
 function regularPackagesOf(pluginDir2) {
-  return subdirectories(pluginDir2).filter((name) => existsSync49(join58(pluginDir2, name, "__init__.py"))).sort();
+  return subdirectories(pluginDir2).filter((name) => existsSync51(join61(pluginDir2, name, "__init__.py"))).sort();
 }
 function bareTestModulesOf(pluginDir2) {
-  const testsDir = join58(pluginDir2, "tests");
-  if (!existsSync49(testsDir)) return [];
-  if (existsSync49(join58(testsDir, "__init__.py"))) return [];
+  const testsDir = join61(pluginDir2, "tests");
+  if (!existsSync51(testsDir)) return [];
+  if (existsSync51(join61(testsDir, "__init__.py"))) return [];
   return readdirSync24(testsDir).filter((f) => f.endsWith(".py") && !PYTEST_SPECIAL.has(f)).sort();
 }
 function findCollisions(servicesDir, pluginDirs) {
@@ -13539,7 +13591,7 @@ function findCollisions(servicesDir, pluginDirs) {
   const gather = (kind, namesOf) => {
     const claims = /* @__PURE__ */ new Map();
     for (const plugin of plugins) {
-      for (const name of namesOf(join58(servicesDir, plugin))) {
+      for (const name of namesOf(join61(servicesDir, plugin))) {
         claims.set(name, [...claims.get(name) ?? [], plugin]);
       }
     }
@@ -13577,8 +13629,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 = join59(root, "services");
-  if (!existsSync50(servicesDir)) {
+  const servicesDir = join62(root, "services");
+  if (!existsSync52(servicesDir)) {
     console.log("\u2713 plugin collision guard: no services/ directory \u2014 nothing to compare");
     return;
   }
@@ -13595,8 +13647,8 @@ async function runPluginCollisionCheck() {
 }
 
 // src/lib/plugin-terraform-guard.ts
-import { existsSync as existsSync51, readFileSync as readFileSync41, readdirSync as readdirSync25 } from "fs";
-import { dirname as dirname10, join as join60, relative as relative10, sep as sep4 } from "path";
+import { existsSync as existsSync53, readFileSync as readFileSync41, 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) {
@@ -13611,9 +13663,9 @@ function findPluginManifests(root) {
     for (const entry of entries) {
       if (entry.isDirectory()) {
         if (SKIP_DIRS4.has(entry.name)) continue;
-        walk2(join60(dir, entry.name));
+        walk2(join63(dir, entry.name));
       } else if (entry.isFile() && entry.name === PLUGIN_MANIFEST_FILE2) {
-        found.push(relative10(root, join60(dir, entry.name)).split(sep4).join("/"));
+        found.push(relative10(root, join63(dir, entry.name)).split(sep4).join("/"));
       }
     }
   };
@@ -13638,14 +13690,14 @@ function readSubscriptions(absManifestPath) {
 }
 function checkPluginTerraform(root) {
   const violations = [];
-  const coreManifest = existsSync51(join60(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
+  const coreManifest = existsSync53(join63(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
   for (const manifest of findPluginManifests(root)) {
     if (coreManifest && !isTemplateOwned(manifest, coreManifest)) continue;
-    const absManifest = join60(root, manifest);
+    const absManifest = join63(root, manifest);
     const subscriptions = readSubscriptions(absManifest);
     if (subscriptions === null) continue;
     const pluginDir2 = dirname10(absManifest);
-    if (existsSync51(join60(pluginDir2, "terraform"))) continue;
+    if (existsSync53(join63(pluginDir2, "terraform"))) continue;
     const relPluginDir = relative10(root, pluginDir2).split(sep4).join("/");
     violations.push({
       manifest,
@@ -13676,12 +13728,12 @@ async function runPluginTerraformCheck() {
 }
 
 // src/scripts/check-plugin-tool-supply.ts
-import { existsSync as existsSync53 } from "fs";
-import { join as join62 } from "path";
+import { existsSync as existsSync55 } from "fs";
+import { join as join65 } from "path";
 
 // src/lib/plugin-tool-supply-audit.ts
-import { existsSync as existsSync52, readFileSync as readFileSync42, readdirSync as readdirSync26, statSync as statSync16 } from "fs";
-import { join as join61 } from "path";
+import { existsSync as existsSync54, readFileSync as readFileSync42, 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";
@@ -14098,7 +14150,7 @@ function listDirs(root) {
   }
   return entries.filter((e) => {
     try {
-      return statSync16(join61(root, e)).isDirectory();
+      return statSync16(join64(root, e)).isDirectory();
     } catch {
       return false;
     }
@@ -14114,7 +14166,7 @@ function walkFiles2(root, accept, skipDir) {
       return;
     }
     for (const entry of entries) {
-      const p = join61(dir, entry);
+      const p = join64(dir, entry);
       let st;
       try {
         st = statSync16(p);
@@ -14140,14 +14192,14 @@ function pluginPythonFiles(pluginDir2) {
   );
 }
 function pluginTerraformFiles(pluginDir2) {
-  const tfDir = join61(pluginDir2, "terraform");
+  const tfDir = join64(pluginDir2, "terraform");
   let entries;
   try {
     entries = readdirSync26(tfDir);
   } catch {
     return [];
   }
-  return entries.filter((e) => e.endsWith(".tf")).map((e) => join61(tfDir, e)).sort();
+  return entries.filter((e) => e.endsWith(".tf")).map((e) => join64(tfDir, e)).sort();
 }
 function extractManifestTools(manifestText) {
   let parsed;
@@ -14399,8 +14451,8 @@ function isSnapshotStale(fetchedAt, now) {
 function normalizeModelId(id) {
   return id.endsWith(":online") ? id.slice(0, -":online".length) : id;
 }
-var CONFIG_PY_PATH = join61("services", "api", "src", "api", "config.py");
-var ORCHESTRATION_SCHEMA_PATH = join61(
+var CONFIG_PY_PATH = join64("services", "api", "src", "api", "config.py");
+var ORCHESTRATION_SCHEMA_PATH = join64(
   "services",
   "api",
   "src",
@@ -14412,10 +14464,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 = join61(repoRoot, CONFIG_PY_PATH);
-  const orchestrationPath = join61(repoRoot, ORCHESTRATION_SCHEMA_PATH);
-  const configMissing = !existsSync52(configPath);
-  const orchestrationSchemaMissing = !existsSync52(orchestrationPath);
+  const configPath = join64(repoRoot, CONFIG_PY_PATH);
+  const orchestrationPath = join64(repoRoot, ORCHESTRATION_SCHEMA_PATH);
+  const configMissing = !existsSync54(configPath);
+  const orchestrationSchemaMissing = !existsSync54(orchestrationPath);
   const knownSet = new Set(knownModelIds);
   const snapshotEmpty = knownModelIds.length === 0;
   const snapshotStale = isSnapshotStale(snapshotFetchedAt, now);
@@ -14486,7 +14538,7 @@ function auditDeclaredModelIds(repoRoot, options = {}) {
 function discoverPluginDirs(pluginsRoot) {
   return listDirs(pluginsRoot).filter((name) => {
     try {
-      return statSync16(join61(pluginsRoot, name, "biffo.plugin.json")).isFile();
+      return statSync16(join64(pluginsRoot, name, "biffo.plugin.json")).isFile();
     } catch {
       return false;
     }
@@ -14499,8 +14551,8 @@ function auditPluginToolSupply(pluginsRoot) {
   let terraformBlind = false;
   let totalDeclaredTools = 0;
   for (const name of pluginNames) {
-    const pluginDir2 = join61(pluginsRoot, name);
-    const manifestText = readFileSync42(join61(pluginDir2, "biffo.plugin.json"), "utf8");
+    const pluginDir2 = join64(pluginsRoot, name);
+    const manifestText = readFileSync42(join64(pluginDir2, "biffo.plugin.json"), "utf8");
     const manifest = extractManifestTools(manifestText);
     if (manifest.parseError) {
       findings.push({
@@ -14598,7 +14650,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 ${join61(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`
       });
     }
   }
@@ -14631,8 +14683,8 @@ function auditPluginToolSupply(pluginsRoot) {
 async function runPluginToolSupplyCheck() {
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
   let allOk = true;
-  const pluginsRoot = join62(root, "services", "_plugins");
-  if (!existsSync53(pluginsRoot)) {
+  const pluginsRoot = join65(root, "services", "_plugins");
+  if (!existsSync55(pluginsRoot)) {
     console.log("\u2713 plugin tool-supply guard: no services/_plugins/ \u2014 nothing to audit");
   } else {
     const report = auditPluginToolSupply(pluginsRoot);
@@ -14662,8 +14714,8 @@ async function runPluginToolSupplyCheck() {
       console.log(`\u2713 plugin tool-supply guard: ${report.summary}`);
     }
   }
-  const servicesApiRoot = join62(root, "services", "api");
-  if (!existsSync53(servicesApiRoot)) {
+  const servicesApiRoot = join65(root, "services", "api");
+  if (!existsSync55(servicesApiRoot)) {
     console.log("\u2713 plugin model-id guard: no services/api/ \u2014 nothing to audit");
   } else {
     const modelReport = auditDeclaredModelIds(root);
@@ -15040,12 +15092,12 @@ async function runSharedFileReductionCheck(args) {
 }
 
 // src/scripts/check-skeleton-drift.ts
-import { existsSync as existsSync54, readdirSync as readdirSync28 } from "fs";
-import { join as join64 } from "path";
+import { existsSync as existsSync56, readdirSync as readdirSync28 } from "fs";
+import { join as join67 } from "path";
 
 // src/lib/skeleton-drift-guard.ts
 import { readFileSync as readFileSync45, readdirSync as readdirSync27, statSync as statSync17 } from "fs";
-import { join as join63 } 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");
@@ -15109,7 +15161,7 @@ function walk(dir, base = dir) {
   }
   for (const entry of entries) {
     if (entry === ".venv" || entry === "node_modules" || entry === ".git") continue;
-    const abs = join63(dir, entry);
+    const abs = join66(dir, entry);
     let isDir;
     try {
       isDir = statSync17(abs).isDirectory();
@@ -15131,7 +15183,7 @@ function auditSkeleton(skeletonRoot, name, rules = SKELETON_RULES) {
       if (!rule.appliesTo(rel)) continue;
       let contents;
       try {
-        contents = readFileSync45(join63(skeletonRoot, rel), "utf8");
+        contents = readFileSync45(join66(skeletonRoot, rel), "utf8");
       } catch {
         continue;
       }
@@ -15160,23 +15212,23 @@ function formatViolations2(violations) {
 
 // src/scripts/check-skeleton-drift.ts
 function discoverSkeletons(root) {
-  const skeletonsDir = join64(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) => existsSync54(join64(skeletonsDir, name, ".github", "workflows", "ci.yml"))).sort();
+  return entries.filter((name) => existsSync56(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 = join64(root, "_skeletons", name);
+    const skeletonRoot = join67(root, "_skeletons", name);
     filesConsidered += findWorkflowFiles(skeletonRoot).length;
-    if (existsSync54(join64(skeletonRoot, "apps", "frontend", "src", "app", "layout.tsx"))) {
+    if (existsSync56(join67(skeletonRoot, "apps", "frontend", "src", "app", "layout.tsx"))) {
       filesConsidered += 1;
     }
   }
@@ -15184,13 +15236,19 @@ async function runSkeletonDriftCheck() {
     `audited ${skeletons.length} skeleton(s) (${skeletons.join(", ") || "none"}), ${filesConsidered} file(s) considered, under ${root}/_skeletons`
   );
   if (skeletons.length === 0) {
+    if (!existsSync56(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.`
+      );
+      return;
+    }
     console.error(
       "\u2717 Skeleton-drift guard: found 0 repo skeletons under _skeletons/ \u2014 this looks like a broken scan, not a repo with no scaffolding. Refusing to report success over zero input."
     );
     process.exit(1);
   }
   const violations = skeletons.flatMap(
-    (name) => auditSkeleton(join64(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");
@@ -15386,8 +15444,8 @@ function rawArgsAfter(subcommand) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync55, readFileSync as readFileSync46 } from "fs";
-import { join as join65, resolve as resolve20 } from "path";
+import { existsSync as existsSync57, readFileSync as readFileSync46 } from "fs";
+import { join as join68, resolve as resolve20 } from "path";
 import chalk21 from "chalk";
 import { Command as Command25 } from "commander";
 
@@ -15782,8 +15840,8 @@ async function runDoctorFixBranches(cwd, facts, deps = { git: new GitAdapter(),
   return reapAllBareBranches(cwd, facts.branches, facts.worktrees, facts.currentBranch, deps);
 }
 function readLocalCoreVersion(cwd) {
-  const path = join65(cwd, INSTANCE_CORE_FILE);
-  if (!existsSync55(path)) return null;
+  const path = join68(cwd, INSTANCE_CORE_FILE);
+  if (!existsSync57(path)) return null;
   try {
     return extractVersionField(readFileSync46(path, "utf8"));
   } catch {
@@ -15805,8 +15863,8 @@ function extractVersionField(contents) {
   return match?.[1] ?? null;
 }
 function readFossil(cwd) {
-  const path = join65(cwd, CORE_VERSION_FILE);
-  if (!existsSync55(path)) return null;
+  const path = join68(cwd, CORE_VERSION_FILE);
+  if (!existsSync57(path)) return null;
   try {
     const value = readFileSync46(path, "utf8").trim();
     return value === "" ? null : value;
@@ -16337,13 +16395,13 @@ import { fileURLToPath as fileURLToPath6 } from "url";
 import { Command as Command27 } from "commander";
 
 // src/lib/packaged-scripts.ts
-import { existsSync as existsSync56 } from "fs";
-import { dirname as dirname11, join as join66 } from "path";
+import { existsSync as existsSync58 } from "fs";
+import { dirname as dirname11, join as join69 } from "path";
 function findPackagedScript(startDir, relativePath) {
   let dir = startDir;
   for (; ; ) {
-    const candidate = join66(dir, relativePath);
-    if (existsSync56(candidate)) return candidate;
+    const candidate = join69(dir, relativePath);
+    if (existsSync58(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.303.2",
+  "version": "0.303.4",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",