@biffo/cli 0.305.1 → 0.307.0

package/_skeletons/plugin-template/README.md

@@ -127,6 +127,46 @@ runtime config rather than tenant-scoped table rows:
 > [ADR-0011](https://github.com/keiranholloway/biffo-template/blob/main/docs/ADR/0011-authorization-is-a-core-concern.md)
 > (authorization is a Core concern, not a plugin) and no longer exists.
 
+## User-facing frontend: the `user_frontend` contract (ADR-0021 §2)
+
+If your plugin ships a founder-facing UI, it declares a `user_frontend` block
+in `biffo.plugin.json`:
+
+```json
+"user_frontend": {
+  "dir": "web/dist",
+  "required_group": "founder"
+}
+```
+
+and ships **`web/` and nothing else** — a built static bundle (`index.html`
+plus hashed `assets/*`, the ordinary Vite build-output shape) at the
+repo-relative path `dir` names. That is the entire contract. In particular a
+`user_frontend` plugin ships **no** `terraform/` frontend resources and
+**no** `deploy-frontend.yml` workflow of its own.
+
+**Who serves it, and why there is nothing to provision.** The shared plugin
+host serves the bundle directly — `GET /api/v1/plugins/<name>/ui` and
+`GET /api/v1/plugins/<name>/ui/{proxy+}` on the API Gateway routes every
+installed plugin already shares — the same way it already serves
+`admin_ingress`'s admin shell. There is no per-plugin S3 origin, no per-plugin
+CloudFront behaviour, and nothing for `biffo plugin install` to provision:
+committing `web/dist/` is the whole deploy. See
+[ADR-0021](../../docs/ADR/0021-shared-plugin-hosting.md) section 2 for the
+full design and why this superseded the older, per-plugin hosting model.
+
+**This retires ADR-0018 section 2's per-plugin frontend shape** — a dedicated
+`aws_s3_bucket` behind the shared CloudFront distribution, wired through a
+`cdn_distribution_arn` module variable and a `frontend_bucket_*` output. That
+shape is fail-closed at install time: `biffo plugin install` and
+`biffo plugin upgrade` **refuse** a plugin whose `terraform/` declares it —
+an `aws_s3_bucket` whose name interpolates `-plugin-…-web`, an output named
+`frontend_bucket_*`, or a `cdn_distribution_arn` variable — with an error
+naming ADR-0021 section 2 and this contract. If you are updating an older
+plugin that still ships one of these, delete `terraform/`'s frontend
+resources (and `deploy-frontend.yml`, if present) and adopt `user_frontend`
+above instead; there is nothing left to provision once you do.
+
 ## Standalone repo, not a monorepo package
 
 Unlike biffo-template's own in-monorepo plugins (e.g. `services/_plugins/orchestrator/`,

package/dist/index.js

@@ -3504,6 +3504,45 @@ function declaredOutputs(moduleDir) {
   }
   return names;
 }
+var RETIRED_FRONTEND_BUCKET_PATTERN = /bucket\s*=\s*"[^"]*-plugin-[^"]*-web"/;
+function declaresRetiredFrontendBucket(moduleDir) {
+  let entries;
+  try {
+    entries = readdirSync3(moduleDir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".tf")) continue;
+    let contents;
+    try {
+      contents = readFileSync10(join13(moduleDir, entry.name), "utf8");
+    } catch {
+      continue;
+    }
+    if (RETIRED_FRONTEND_BUCKET_PATTERN.test(contents)) return true;
+  }
+  return false;
+}
+function findRetiredFrontendShape(terraformDir) {
+  const reasons = [];
+  if (!existsSync12(terraformDir)) return reasons;
+  if (declaresRetiredFrontendBucket(terraformDir)) {
+    reasons.push('an aws_s3_bucket whose name interpolates "-plugin-...-web"');
+  }
+  for (const name of [...declaredOutputs(terraformDir)].sort()) {
+    if (name.startsWith("frontend_bucket")) {
+      reasons.push(`an output named "${name}"`);
+    }
+  }
+  if (declaredVariables(terraformDir).has("cdn_distribution_arn")) {
+    reasons.push('a "cdn_distribution_arn" variable');
+  }
+  return reasons;
+}
+function retiredFrontendShapeError(pluginName, reasons) {
+  return `Plugin '${pluginName}' ships a terraform/ frontend on the retired ADR-0018 \xA72 per-plugin hosting shape: it declares ${reasons.join(", ")}. ADR-0021 \xA72 replaced this \u2014 a user-facing plugin's frontend is served by the shared plugin host directly from the manifest's \`user_frontend\` field (\`{ dir, required_group }\`); it ships \`web/\` and nothing else, with no terraform/ frontend and no deploy-frontend.yml. Update the plugin to the \`user_frontend\` contract (see _skeletons/plugin-template/README.md) before installing it here.`;
+}
 function renderArguments(args, indent) {
   const width = Math.max(...args.map(([key]) => key.length));
   return args.map(([key, value]) => `${indent}${key.padEnd(width)} = ${value}`).join("\n");
@@ -9488,6 +9527,10 @@ async function runPluginInstall(target, options, deps) {
     log.success(
       `Manifest valid \u2014 ${manifest.tables.length} table(s), ${manifest.api_routes.length} route(s)`
     );
+    const retiredShapeReasons = findRetiredFrontendShape(join33(source.sourceDir, "terraform"));
+    if (retiredShapeReasons.length > 0) {
+      throw new Error(retiredFrontendShapeError(pluginName, retiredShapeReasons));
+    }
     if (inTreeSource) {
       log.info(`${relTargetDir}/ is already in this checkout \u2014 installing in place.`);
     } else {
@@ -10256,6 +10299,10 @@ async function runPluginUpgrade(target, options, deps) {
     log.success(
       `Manifest valid \u2014 ${manifest.tables.length} table(s), ${manifest.api_routes.length} route(s)`
     );
+    const retiredShapeReasons = findRetiredFrontendShape(join38(tmpDir, "terraform"));
+    if (retiredShapeReasons.length > 0) {
+      throw new Error(retiredFrontendShapeError(entry.name, retiredShapeReasons));
+    }
     if (!existsSync36(join38(tmpDir, "terraform"))) {
       refuseIfModuleStillReferenced(options.cwd, modulesDir, entry.name);
     }
@@ -10370,6 +10417,10 @@ async function runLocalPluginRefresh(localPath, options, deps) {
     log.success(
       `Manifest valid \u2014 ${manifest.tables.length} table(s), ${manifest.api_routes.length} route(s)`
     );
+    const retiredShapeReasons = findRetiredFrontendShape(join38(source.sourceDir, "terraform"));
+    if (retiredShapeReasons.length > 0) {
+      throw new Error(retiredFrontendShapeError(source.name, retiredShapeReasons));
+    }
     if (!existsSync36(join38(source.sourceDir, "terraform"))) {
       refuseIfModuleStillReferenced(options.cwd, modulesDir, source.name);
     }
@@ -12335,8 +12386,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: existsSync59 } = await import("fs");
-      if (existsSync59(messageFile)) commitMessage = readFileSync47(messageFile, "utf8");
+      const { readFileSync: readFileSync48, existsSync: existsSync59 } = await import("fs");
+      if (existsSync59(messageFile)) commitMessage = readFileSync48(messageFile, "utf8");
     }
   } else {
     const base = process.env["GITHUB_BASE_REF"] ?? args[0];
@@ -13396,9 +13447,244 @@ baseline was ${String(ratchet.baseline)}, now ${String(ratchet.count)}. See biff
   }
 }
 
+// src/lib/ownership-header-claim-guard.ts
+import { readFileSync as readFileSync39 } from "fs";
+import { join as join58 } from "path";
+var OWNERSHIP_HEADER_SWEEP_DIRS = [
+  "scripts",
+  ".githooks",
+  ".github",
+  "services",
+  "cli",
+  "infra"
+];
+var STRICT_MARKER = /(?<!`)(?:INSTANCE-OWNED|NOT a template file)(?!`)/;
+var SELF_REFERENTIAL_CLAIM = /\b(?:[Tt]his|[Ii]t)\b(?:\s+\S+){0,3}\s+(?:is|are|stays|remains)\s+(?:\*\*)?(template-owned|user-owned)\b/;
+var EM_DASH_FIRST_LINE_CLAIM = /[—–]\s*(template-owned|user-owned)\b/;
+var MAX_HEADER_LINES = 10;
+function claimFor(matchedPhrase) {
+  return /^template-owned$/i.test(matchedPhrase) ? "template" : "user";
+}
+function claimInText(text) {
+  const candidates = [];
+  const strict = STRICT_MARKER.exec(text);
+  if (strict)
+    candidates.push({ matchedPhrase: strict[0], claim: claimFor(strict[0]), index: strict.index });
+  const grammatical = SELF_REFERENTIAL_CLAIM.exec(text);
+  if (grammatical) {
+    const phrase = grammatical[1];
+    candidates.push({ matchedPhrase: phrase, claim: claimFor(phrase), index: grammatical.index });
+  }
+  const firstLine = text.split("\n", 1)[0] ?? "";
+  const emDash = EM_DASH_FIRST_LINE_CLAIM.exec(firstLine);
+  if (emDash) {
+    const phrase = emDash[1];
+    candidates.push({ matchedPhrase: phrase, claim: claimFor(phrase), index: emDash.index });
+  }
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => a.index - b.index);
+  return candidates[0] ?? null;
+}
+function fileExtension(path) {
+  const dot = path.lastIndexOf(".");
+  const slash = path.lastIndexOf("/");
+  return dot > slash ? path.slice(dot).toLowerCase() : "";
+}
+function isCommentLine(line) {
+  return line.trim().startsWith("#");
+}
+function lineAt(lines, i) {
+  return lines[i] ?? "";
+}
+function leadingHashCommentEnd(lines, start) {
+  let i = start;
+  while (i < lines.length) {
+    if (isCommentLine(lineAt(lines, i))) {
+      i++;
+      continue;
+    }
+    if (lineAt(lines, i).trim() === "") {
+      let j = i + 1;
+      while (j < lines.length && lineAt(lines, j).trim() === "") j++;
+      if (j < lines.length && isCommentLine(lineAt(lines, j))) {
+        i = j;
+        continue;
+      }
+      return i;
+    }
+    return i;
+  }
+  return i;
+}
+function defaultHeaderRange(lines) {
+  const start = lineAt(lines, 0).startsWith("#!") ? 1 : 0;
+  const end = leadingHashCommentEnd(lines, start);
+  return end > start ? [start, end] : null;
+}
+function pythonHeaderRange(lines) {
+  let i = lineAt(lines, 0).startsWith("#!") ? 1 : 0;
+  while (i < lines.length && lineAt(lines, i).trim() === "") i++;
+  if (i >= lines.length) return null;
+  const first = lineAt(lines, i);
+  const trimmed = first.trimStart();
+  const quote = trimmed.startsWith('"""') ? '"""' : trimmed.startsWith("'''") ? "'''" : null;
+  if (quote) {
+    const afterOpen = first.slice(first.indexOf(quote) + 3);
+    if (afterOpen.includes(quote)) return [i, i + 1];
+    let j = i + 1;
+    while (j < lines.length && !lineAt(lines, j).includes(quote)) j++;
+    return [i, Math.min(j + 1, lines.length)];
+  }
+  const end = leadingHashCommentEnd(lines, i);
+  return end > i ? [i, end] : null;
+}
+function jsHeaderRange(lines) {
+  let i = 0;
+  while (i < lines.length && (lineAt(lines, i).trim() === "" || lineAt(lines, i).trim().startsWith("import "))) {
+    i++;
+  }
+  if (i >= lines.length) return null;
+  const first = lineAt(lines, i).trim();
+  if (first.startsWith("/*")) {
+    let j = i;
+    while (j < lines.length && !lineAt(lines, j).includes("*/")) j++;
+    return [i, Math.min(j + 1, lines.length)];
+  }
+  if (first.startsWith("//")) {
+    let j = i;
+    while (j < lines.length && (lineAt(lines, j).trim().startsWith("//") || lineAt(lines, j).trim() === ""))
+      j++;
+    return [i, j];
+  }
+  return null;
+}
+function headerRange(path, lines) {
+  const ext = fileExtension(path);
+  let range;
+  if (ext === ".py") range = pythonHeaderRange(lines);
+  else if (ext === ".ts" || ext === ".tsx" || ext === ".js" || ext === ".mjs")
+    range = jsHeaderRange(lines);
+  else if (ext === ".md")
+    range = [0, Math.min(15, lines.length)];
+  else if (ext === ".json")
+    return null;
+  else range = defaultHeaderRange(lines);
+  if (!range) return null;
+  const [start, end] = range;
+  return [start, Math.min(end, start + MAX_HEADER_LINES)];
+}
+function findJsonDescriptionClaim(path, content) {
+  let data;
+  try {
+    data = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  if (typeof data !== "object" || data === null) return null;
+  const description = data["description"];
+  if (typeof description !== "string") return null;
+  const match = /INSTANCE-OWNED|NOT a template file|user-owned|template-owned/i.exec(description);
+  if (!match) return null;
+  const lineIndex = content.split("\n").findIndex((l) => l.includes('"description"'));
+  return {
+    path,
+    claim: claimFor(match[0]),
+    matchedPhrase: match[0],
+    line: lineIndex === -1 ? 1 : lineIndex + 1
+  };
+}
+function findHeaderClaim(path, content) {
+  if (fileExtension(path) === ".json") return findJsonDescriptionClaim(path, content);
+  const lines = content.split("\n");
+  const range = headerRange(path, lines);
+  if (!range) return null;
+  const [start, end] = range;
+  const windowText = lines.slice(start, end).join("\n");
+  const found = claimInText(windowText);
+  if (!found) return null;
+  const line = start + windowText.slice(0, found.index).split("\n").length;
+  return { path, claim: found.claim, matchedPhrase: found.matchedPhrase, line };
+}
+function sweepOwnershipHeaderClaims(root, options = {}) {
+  const tracked = options.git ? gitTrackedFiles(root, options.git) : gitTrackedFiles(root);
+  if (!tracked) return [];
+  const files = [...tracked].filter((p) => OWNERSHIP_HEADER_SWEEP_DIRS.some((dir) => p === dir || p.startsWith(`${dir}/`))).sort();
+  const hits = [];
+  for (const rel of files) {
+    let content;
+    try {
+      content = readFileSync39(join58(root, rel), "utf8");
+    } catch {
+      continue;
+    }
+    const hit = findHeaderClaim(rel, content);
+    if (hit) hits.push(hit);
+  }
+  return hits;
+}
+function matchesReleased(relPath, manifest) {
+  return (manifest.released ?? []).some((p) => relPath === p || relPath.startsWith(p));
+}
+function checkOwnershipHeaderClaims(hits, manifest) {
+  const out = [];
+  for (const hit of hits) {
+    const manifestSaysTemplateOwned = isTemplateOwned(hit.path, manifest);
+    const released = matchesReleased(hit.path, manifest);
+    const agrees = hit.claim === "template" ? manifestSaysTemplateOwned || released : !manifestSaysTemplateOwned && !released;
+    if (!agrees) {
+      out.push({ ...hit, manifestSaysTemplateOwned });
+    }
+  }
+  return out;
+}
+
+// src/scripts/check-ownership-header-claim.ts
+async function runOwnershipHeaderClaimCheck() {
+  const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  const ownership = classifyRepoOwnership(root);
+  if (ownership === "satellite") {
+    console.log(
+      "\u2713 ownership-header-claim guard: skipped \u2014 this repo carries no core-manifest.json, so there is no ownership authority to check a header claim against."
+    );
+    return;
+  }
+  const manifest = readCoreManifest(root);
+  const hits = sweepOwnershipHeaderClaims(root);
+  console.log(
+    `examined ${hits.length} file(s) carrying an ownership-style header claim under scripts/, .githooks/, .github/, services/, cli/, infra/`
+  );
+  if (hits.length === 0) {
+    console.error(
+      "\u2717 ownership-header-claim guard: swept zero files \u2014 refusing a false green rather than assuming every ownership-style header vanished."
+    );
+    process.exit(1);
+    return;
+  }
+  const disagreements = checkOwnershipHeaderClaims(hits, manifest);
+  if (disagreements.length > 0) {
+    console.error(
+      `\u2717 ownership-header-claim guard: ${disagreements.length} of ${hits.length} file(s) carry a header claim core-manifest.json disagrees with (#1911):
+`
+    );
+    for (const d of disagreements) {
+      console.error(
+        `  ${d.path}:${d.line}  header says "${d.matchedPhrase}" (${d.claim}-owned), but core-manifest.json says ${d.manifestSaysTemplateOwned ? "template-owned" : "user-owned"}`
+      );
+    }
+    console.error(
+      "\nEither fix the header to match core-manifest.json, or fix core-manifest.json to match reality \u2014 never leave the two disagreeing."
+    );
+    process.exit(1);
+    return;
+  }
+  console.log(
+    `\u2713 ownership-header-claim guard: examined ${hits.length} file(s), all agree with core-manifest.json`
+  );
+}
+
 // src/scripts/check-pipe-trap.ts
-import { readFileSync as readFileSync39, readdirSync as readdirSync23 } from "fs";
-import { join as join58, relative as relative9 } from "path";
+import { readFileSync as readFileSync40, readdirSync as readdirSync23 } from "fs";
+import { join as join59, relative as relative9 } from "path";
 
 // src/lib/pipe-trap-guard.ts
 var STATUS_BEARING = [
@@ -13494,7 +13780,7 @@ function findPipeTraps(source) {
 function shellFiles(root) {
   const out = [];
   for (const dir of ["scripts", ".githooks"]) {
-    const full = join58(root, dir);
+    const full = join59(root, dir);
     let entries;
     try {
       entries = readdirSync23(full, { withFileTypes: true });
@@ -13504,7 +13790,7 @@ function shellFiles(root) {
     for (const entry of entries) {
       if (!entry.isFile()) continue;
       if (dir === "scripts" && !entry.name.endsWith(".sh")) continue;
-      out.push(join58(full, entry.name));
+      out.push(join59(full, entry.name));
     }
   }
   return out;
@@ -13520,7 +13806,7 @@ async function runPipeTrapCheck() {
     process.exit(1);
   }
   const findings = files.flatMap(
-    (file) => findPipeTraps(readFileSync39(file, "utf8")).map(
+    (file) => findPipeTraps(readFileSync40(file, "utf8")).map(
       (t) => `${relative9(root, file)}:${t.line}  ${t.text}
     ${t.reason}`
     )
@@ -13538,11 +13824,11 @@ async function runPipeTrapCheck() {
 
 // src/scripts/check-plugin-allowlist-convention.ts
 import { existsSync as existsSync50 } from "fs";
-import { join as join60 } from "path";
+import { join as join61 } from "path";
 
 // src/lib/plugin-allowlist-convention.ts
-import { readFileSync as readFileSync40 } from "fs";
-import { join as join59 } from "path";
+import { readFileSync as readFileSync41 } from "fs";
+import { join as join60 } 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";
@@ -13553,7 +13839,7 @@ var PLUGIN = "<plugin>";
 var ACCOUNT = "<account>";
 function read(repoRoot, relative11) {
   try {
-    return readFileSync40(join59(repoRoot, relative11), "utf8");
+    return readFileSync41(join60(repoRoot, relative11), "utf8");
   } catch {
     throw new Error(`plugin-allowlist drift guard: cannot read ${relative11}`);
   }
@@ -13656,7 +13942,7 @@ var REQUIRED_SOURCES = [
 ];
 async function runPluginAllowlistConventionCheck() {
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
-  const missing = REQUIRED_SOURCES.filter((relative11) => !existsSync50(join60(root, relative11)));
+  const missing = REQUIRED_SOURCES.filter((relative11) => !existsSync50(join61(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.`
@@ -13688,11 +13974,11 @@ async function runPluginAllowlistConventionCheck() {
 
 // src/scripts/check-plugin-collisions.ts
 import { existsSync as existsSync52 } from "fs";
-import { join as join62 } from "path";
+import { join as join63 } from "path";
 
 // src/lib/plugin-collision-guard.ts
 import { existsSync as existsSync51, readdirSync as readdirSync24, statSync as statSync15 } from "fs";
-import { join as join61 } from "path";
+import { join as join62 } 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) {
@@ -13700,19 +13986,19 @@ function subdirectories(dir) {
   return readdirSync24(dir).filter((entry) => {
     if (IGNORED_DIRS.has(entry) || entry.startsWith(".")) return false;
     try {
-      return statSync15(join61(dir, entry)).isDirectory();
+      return statSync15(join62(dir, entry)).isDirectory();
     } catch {
       return false;
     }
   });
 }
 function regularPackagesOf(pluginDir2) {
-  return subdirectories(pluginDir2).filter((name) => existsSync51(join61(pluginDir2, name, "__init__.py"))).sort();
+  return subdirectories(pluginDir2).filter((name) => existsSync51(join62(pluginDir2, name, "__init__.py"))).sort();
 }
 function bareTestModulesOf(pluginDir2) {
-  const testsDir = join61(pluginDir2, "tests");
+  const testsDir = join62(pluginDir2, "tests");
   if (!existsSync51(testsDir)) return [];
-  if (existsSync51(join61(testsDir, "__init__.py"))) return [];
+  if (existsSync51(join62(testsDir, "__init__.py"))) return [];
   return readdirSync24(testsDir).filter((f) => f.endsWith(".py") && !PYTEST_SPECIAL.has(f)).sort();
 }
 function findCollisions(servicesDir, pluginDirs) {
@@ -13721,7 +14007,7 @@ function findCollisions(servicesDir, pluginDirs) {
   const gather = (kind, namesOf) => {
     const claims = /* @__PURE__ */ new Map();
     for (const plugin of plugins) {
-      for (const name of namesOf(join61(servicesDir, plugin))) {
+      for (const name of namesOf(join62(servicesDir, plugin))) {
         claims.set(name, [...claims.get(name) ?? [], plugin]);
       }
     }
@@ -13759,7 +14045,7 @@ 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 = join62(root, "services");
+  const servicesDir = join63(root, "services");
   if (!existsSync52(servicesDir)) {
     console.log("\u2713 plugin collision guard: no services/ directory \u2014 nothing to compare");
     return;
@@ -13777,8 +14063,8 @@ async function runPluginCollisionCheck() {
 }
 
 // src/lib/plugin-terraform-guard.ts
-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";
+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";
 var SKIP_DIRS4 = /* @__PURE__ */ new Set(["node_modules", ".git", ".worktrees", "dist", ".venv", "__pycache__"]);
 var PLUGIN_MANIFEST_FILE2 = "biffo.plugin.json";
 function findPluginManifests(root) {
@@ -13793,9 +14079,9 @@ function findPluginManifests(root) {
     for (const entry of entries) {
       if (entry.isDirectory()) {
         if (SKIP_DIRS4.has(entry.name)) continue;
-        walk2(join63(dir, entry.name));
+        walk2(join64(dir, entry.name));
       } else if (entry.isFile() && entry.name === PLUGIN_MANIFEST_FILE2) {
-        found.push(relative10(root, join63(dir, entry.name)).split(sep4).join("/"));
+        found.push(relative10(root, join64(dir, entry.name)).split(sep4).join("/"));
       }
     }
   };
@@ -13805,7 +14091,7 @@ function findPluginManifests(root) {
 function readSubscriptions(absManifestPath) {
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync41(absManifestPath, "utf8"));
+    parsed = JSON.parse(readFileSync42(absManifestPath, "utf8"));
   } catch {
     return null;
   }
@@ -13820,14 +14106,14 @@ function readSubscriptions(absManifestPath) {
 }
 function checkPluginTerraform(root) {
   const violations = [];
-  const coreManifest = existsSync53(join63(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
+  const coreManifest = existsSync53(join64(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
   for (const manifest of findPluginManifests(root)) {
     if (coreManifest && !isTemplateOwned(manifest, coreManifest)) continue;
-    const absManifest = join63(root, manifest);
+    const absManifest = join64(root, manifest);
     const subscriptions = readSubscriptions(absManifest);
     if (subscriptions === null) continue;
     const pluginDir2 = dirname10(absManifest);
-    if (existsSync53(join63(pluginDir2, "terraform"))) continue;
+    if (existsSync53(join64(pluginDir2, "terraform"))) continue;
     const relPluginDir = relative10(root, pluginDir2).split(sep4).join("/");
     violations.push({
       manifest,
@@ -13859,11 +14145,11 @@ async function runPluginTerraformCheck() {
 
 // src/scripts/check-plugin-tool-supply.ts
 import { existsSync as existsSync55 } from "fs";
-import { join as join65 } from "path";
+import { join as join66 } from "path";
 
 // src/lib/plugin-tool-supply-audit.ts
-import { existsSync as existsSync54, readFileSync as readFileSync42, readdirSync as readdirSync26, statSync as statSync16 } from "fs";
-import { join as join64 } from "path";
+import { existsSync as existsSync54, readFileSync as readFileSync43, readdirSync as readdirSync26, statSync as statSync16 } from "fs";
+import { join as join65 } from "path";
 
 // src/lib/openrouter-model-snapshot.ts
 var OPENROUTER_MODEL_SNAPSHOT_FETCHED_AT = "2026-08-10T06:39:01Z";
@@ -14280,7 +14566,7 @@ function listDirs(root) {
   }
   return entries.filter((e) => {
     try {
-      return statSync16(join64(root, e)).isDirectory();
+      return statSync16(join65(root, e)).isDirectory();
     } catch {
       return false;
     }
@@ -14296,7 +14582,7 @@ function walkFiles2(root, accept, skipDir) {
       return;
     }
     for (const entry of entries) {
-      const p = join64(dir, entry);
+      const p = join65(dir, entry);
       let st;
       try {
         st = statSync16(p);
@@ -14322,14 +14608,14 @@ function pluginPythonFiles(pluginDir2) {
   );
 }
 function pluginTerraformFiles(pluginDir2) {
-  const tfDir = join64(pluginDir2, "terraform");
+  const tfDir = join65(pluginDir2, "terraform");
   let entries;
   try {
     entries = readdirSync26(tfDir);
   } catch {
     return [];
   }
-  return entries.filter((e) => e.endsWith(".tf")).map((e) => join64(tfDir, e)).sort();
+  return entries.filter((e) => e.endsWith(".tf")).map((e) => join65(tfDir, e)).sort();
 }
 function extractManifestTools(manifestText) {
   let parsed;
@@ -14581,8 +14867,8 @@ function isSnapshotStale(fetchedAt, now) {
 function normalizeModelId(id) {
   return id.endsWith(":online") ? id.slice(0, -":online".length) : id;
 }
-var CONFIG_PY_PATH = join64("services", "api", "src", "api", "config.py");
-var ORCHESTRATION_SCHEMA_PATH = join64(
+var CONFIG_PY_PATH = join65("services", "api", "src", "api", "config.py");
+var ORCHESTRATION_SCHEMA_PATH = join65(
   "services",
   "api",
   "src",
@@ -14594,8 +14880,8 @@ 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 = join64(repoRoot, CONFIG_PY_PATH);
-  const orchestrationPath = join64(repoRoot, ORCHESTRATION_SCHEMA_PATH);
+  const configPath = join65(repoRoot, CONFIG_PY_PATH);
+  const orchestrationPath = join65(repoRoot, ORCHESTRATION_SCHEMA_PATH);
   const configMissing = !existsSync54(configPath);
   const orchestrationSchemaMissing = !existsSync54(orchestrationPath);
   const knownSet = new Set(knownModelIds);
@@ -14615,13 +14901,13 @@ function auditDeclaredModelIds(repoRoot, options = {}) {
   };
   let settingsBlind = false;
   if (!configMissing) {
-    const settingsFields = extractSettingsModelFields(readFileSync42(configPath, "utf8"));
+    const settingsFields = extractSettingsModelFields(readFileSync43(configPath, "utf8"));
     if (settingsFields.length === 0) settingsBlind = true;
     for (const { field, value } of settingsFields) record(`${CONFIG_PY_PATH}#${field}`, value);
   }
   let curatedFieldsBlind = false;
   if (!orchestrationSchemaMissing) {
-    const curated = extractCuratedModelFields(readFileSync42(orchestrationPath, "utf8"));
+    const curated = extractCuratedModelFields(readFileSync43(orchestrationPath, "utf8"));
     if (curated.rawFieldCount > 0 && curated.fields.every((f) => f.defaultValue === null && f.optionValues.length === 0)) {
       curatedFieldsBlind = true;
     }
@@ -14668,7 +14954,7 @@ function auditDeclaredModelIds(repoRoot, options = {}) {
 function discoverPluginDirs(pluginsRoot) {
   return listDirs(pluginsRoot).filter((name) => {
     try {
-      return statSync16(join64(pluginsRoot, name, "biffo.plugin.json")).isFile();
+      return statSync16(join65(pluginsRoot, name, "biffo.plugin.json")).isFile();
     } catch {
       return false;
     }
@@ -14681,8 +14967,8 @@ function auditPluginToolSupply(pluginsRoot) {
   let terraformBlind = false;
   let totalDeclaredTools = 0;
   for (const name of pluginNames) {
-    const pluginDir2 = join64(pluginsRoot, name);
-    const manifestText = readFileSync42(join64(pluginDir2, "biffo.plugin.json"), "utf8");
+    const pluginDir2 = join65(pluginsRoot, name);
+    const manifestText = readFileSync43(join65(pluginDir2, "biffo.plugin.json"), "utf8");
     const manifest = extractManifestTools(manifestText);
     if (manifest.parseError) {
       findings.push({
@@ -14700,13 +14986,13 @@ function auditPluginToolSupply(pluginsRoot) {
     totalDeclaredTools += manifest.tools.length;
     const pySources = pluginPythonFiles(pluginDir2).map((f) => ({
       file: f,
-      text: readFileSync42(f, "utf8")
+      text: readFileSync43(f, "utf8")
     }));
     const resolver = buildSymbolResolver(pySources);
     const registry = extractToolRegistryEntries(pySources, resolver);
     if (registry.rawToolDefinitionCount > 0 && registry.entries.length === 0) registryBlind = true;
     const tfFiles = pluginTerraformFiles(pluginDir2);
-    const tfText = tfFiles.map((f) => readFileSync42(f, "utf8")).join("\n");
+    const tfText = tfFiles.map((f) => readFileSync43(f, "utf8")).join("\n");
     const terraform = extractTerraformEnvKeys(tfText);
     if (terraform.rawMarkerCount > 0 && terraform.resolvedBlockCount === 0) terraformBlind = true;
     for (const toolName of manifest.tools) {
@@ -14780,7 +15066,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 ${join64(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 ${join65(pluginDir2, "terraform")}, so this deployment can never supply it`
       });
     }
   }
@@ -14813,7 +15099,7 @@ function auditPluginToolSupply(pluginsRoot) {
 async function runPluginToolSupplyCheck() {
   const root = (await execa("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
   let allOk = true;
-  const pluginsRoot = join65(root, "services", "_plugins");
+  const pluginsRoot = join66(root, "services", "_plugins");
   if (!existsSync55(pluginsRoot)) {
     console.log("\u2713 plugin tool-supply guard: no services/_plugins/ \u2014 nothing to audit");
   } else {
@@ -14844,7 +15130,7 @@ async function runPluginToolSupplyCheck() {
       console.log(`\u2713 plugin tool-supply guard: ${report.summary}`);
     }
   }
-  const servicesApiRoot = join65(root, "services", "api");
+  const servicesApiRoot = join66(root, "services", "api");
   if (!existsSync55(servicesApiRoot)) {
     console.log("\u2713 plugin model-id guard: no services/api/ \u2014 nothing to audit");
   } else {
@@ -15019,10 +15305,10 @@ async function runReleaseSubjectCheck(argv) {
 }
 
 // src/scripts/check-shared-file-reduction.ts
-import { readFileSync as readFileSync44 } from "fs";
+import { readFileSync as readFileSync45 } from "fs";
 
 // src/lib/shared-file-reduction-guard.ts
-import { readFileSync as readFileSync43 } from "fs";
+import { readFileSync as readFileSync44 } from "fs";
 var LEAF_TEST_CALLS = /* @__PURE__ */ new Set(["it", "test"]);
 var SUITE_CALLS = /* @__PURE__ */ new Set(["describe", "suite"]);
 var TEST_FILE_PATTERN = /\.(test|spec)\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
@@ -15149,7 +15435,7 @@ function formatReductionReport(report) {
 // src/scripts/check-shared-file-reduction.ts
 function readStdin() {
   try {
-    return readFileSync44(0, "utf8");
+    return readFileSync45(0, "utf8");
   } catch {
     return "";
   }
@@ -15166,15 +15452,15 @@ function pairsFromTsv(tsv) {
     const [target, existingPath, incomingPath] = fields;
     pairs.push({
       target,
-      existing: readFileSync44(existingPath, "utf8"),
-      incoming: readFileSync44(incomingPath, "utf8")
+      existing: readFileSync45(existingPath, "utf8"),
+      incoming: readFileSync45(incomingPath, "utf8")
     });
   }
   return pairs;
 }
 function loadAccepted(manifestPath) {
   if (!manifestPath) return {};
-  const parsed = JSON.parse(readFileSync44(manifestPath, "utf8"));
+  const parsed = JSON.parse(readFileSync45(manifestPath, "utf8"));
   return parsed.acceptedReductions ?? {};
 }
 async function runSharedFileReductionCheck(args) {
@@ -15182,13 +15468,13 @@ async function runSharedFileReductionCheck(args) {
   let accepted;
   try {
     if (args.pairs) {
-      pairs = pairsFromTsv(args.pairs === "-" ? readStdin() : readFileSync44(args.pairs, "utf8"));
+      pairs = pairsFromTsv(args.pairs === "-" ? readStdin() : readFileSync45(args.pairs, "utf8"));
     } else if (args.target && args.existing && args.incoming) {
       pairs = [
         {
           target: args.target,
-          existing: readFileSync44(args.existing, "utf8"),
-          incoming: readFileSync44(args.incoming, "utf8")
+          existing: readFileSync45(args.existing, "utf8"),
+          incoming: readFileSync45(args.incoming, "utf8")
         }
       ];
     } else {
@@ -15223,11 +15509,11 @@ async function runSharedFileReductionCheck(args) {
 
 // src/scripts/check-skeleton-drift.ts
 import { existsSync as existsSync56, readdirSync as readdirSync28 } from "fs";
-import { join as join67 } from "path";
+import { join as join68 } from "path";
 
 // src/lib/skeleton-drift-guard.ts
-import { readFileSync as readFileSync45, readdirSync as readdirSync27, statSync as statSync17 } from "fs";
-import { join as join66 } from "path";
+import { readFileSync as readFileSync46, readdirSync as readdirSync27, statSync as statSync17 } from "fs";
+import { join as join67 } 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");
@@ -15291,7 +15577,7 @@ function walk(dir, base = dir) {
   }
   for (const entry of entries) {
     if (entry === ".venv" || entry === "node_modules" || entry === ".git") continue;
-    const abs = join66(dir, entry);
+    const abs = join67(dir, entry);
     let isDir;
     try {
       isDir = statSync17(abs).isDirectory();
@@ -15313,7 +15599,7 @@ function auditSkeleton(skeletonRoot, name, rules = SKELETON_RULES) {
       if (!rule.appliesTo(rel)) continue;
       let contents;
       try {
-        contents = readFileSync45(join66(skeletonRoot, rel), "utf8");
+        contents = readFileSync46(join67(skeletonRoot, rel), "utf8");
       } catch {
         continue;
       }
@@ -15342,23 +15628,23 @@ function formatViolations2(violations) {
 
 // src/scripts/check-skeleton-drift.ts
 function discoverSkeletons(root) {
-  const skeletonsDir = join67(root, "_skeletons");
+  const skeletonsDir = join68(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(join67(skeletonsDir, name, ".github", "workflows", "ci.yml"))).sort();
+  return entries.filter((name) => existsSync56(join68(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 = join67(root, "_skeletons", name);
+    const skeletonRoot = join68(root, "_skeletons", name);
     filesConsidered += findWorkflowFiles(skeletonRoot).length;
-    if (existsSync56(join67(skeletonRoot, "apps", "frontend", "src", "app", "layout.tsx"))) {
+    if (existsSync56(join68(skeletonRoot, "apps", "frontend", "src", "app", "layout.tsx"))) {
       filesConsidered += 1;
     }
   }
@@ -15366,7 +15652,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(join67(root, "_skeletons"))) {
+    if (!existsSync56(join68(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.`
       );
@@ -15378,7 +15664,7 @@ async function runSkeletonDriftCheck() {
     process.exit(1);
   }
   const violations = skeletons.flatMap(
-    (name) => auditSkeleton(join67(root, "_skeletons", name), name)
+    (name) => auditSkeleton(join68(root, "_skeletons", name), name)
   );
   if (violations.length > 0) {
     console.error("\u2717 Skeleton-drift guard: drift found between this repo and its scaffolding\n");
@@ -15414,7 +15700,7 @@ async function runTerraformInputCheck() {
 
 // src/commands/check.ts
 var checkCommand = new Command24("check").description(
-  "Repo guards (ownership, release subject, plugin terraform, plugin collisions, eventbridge-log-permissions, plugin-tool-supply, core-direct-paths, instance-adoption, orphan-ratchet, cognito-invite-template, lambda-output, pipe-trap, codeql-suppression, skeleton-drift, terraform-input, plugin-allowlist-convention, migration-body-change, distribution-inventory, distribution-remote-state, api-gateway-integration) run in CI and git hooks, plus out-of-band audits (branch protection, plugin-staleness)"
+  "Repo guards (ownership, ownership-header-claim, release subject, plugin terraform, plugin collisions, eventbridge-log-permissions, plugin-tool-supply, core-direct-paths, instance-adoption, orphan-ratchet, cognito-invite-template, lambda-output, pipe-trap, codeql-suppression, skeleton-drift, terraform-input, plugin-allowlist-convention, migration-body-change, distribution-inventory, distribution-remote-state, api-gateway-integration) run in CI and git hooks, plus out-of-band audits (branch protection, plugin-staleness)"
 );
 checkCommand.command("ownership").description("Refuse changes to template-owned paths in an instance (#370)").argument("[base]", "Base branch to diff against; defaults to $GITHUB_BASE_REF").option("--staged <messageFile>", "Check staged changes instead of a branch diff (commit hook)").allowExcessArguments(true).action(async () => {
   await runOwnershipCheck(rawArgsAfter("ownership"));
@@ -15503,6 +15789,11 @@ checkCommand.command("orphan-ratchet").description(
     await runOrphanRatchetCheck(opts);
   }
 );
+checkCommand.command("ownership-header-claim").description(
+  `Refuse a file whose own header comment claims INSTANCE-OWNED/template-owned/user-owned/"NOT a template file" while core-manifest.json's real longest-prefix-match answer disagrees (#1911) \u2014 scripts/verify-deployed.checks lived this exact gap (#1706/#1707) until a human happened to notice by hand; nothing else compared the two documents.`
+).action(async () => {
+  await runOwnershipHeaderClaimCheck();
+});
 checkCommand.command("cognito-invite-template").description(
   "Refuse a Cognito invite_message_template missing a required member or placeholder (#356) \u2014 terraform validate is silent on this, so a fresh deploy fails on its first apply"
 ).action(async () => {
@@ -15574,8 +15865,8 @@ function rawArgsAfter(subcommand) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync57, readFileSync as readFileSync46 } from "fs";
-import { join as join68, resolve as resolve20 } from "path";
+import { existsSync as existsSync57, readFileSync as readFileSync47 } from "fs";
+import { join as join69, resolve as resolve20 } from "path";
 import chalk21 from "chalk";
 import { Command as Command25 } from "commander";
 
@@ -15970,10 +16261,10 @@ async function runDoctorFixBranches(cwd, facts, deps = { git: new GitAdapter(),
   return reapAllBareBranches(cwd, facts.branches, facts.worktrees, facts.currentBranch, deps);
 }
 function readLocalCoreVersion(cwd) {
-  const path = join68(cwd, INSTANCE_CORE_FILE);
+  const path = join69(cwd, INSTANCE_CORE_FILE);
   if (!existsSync57(path)) return null;
   try {
-    return extractVersionField(readFileSync46(path, "utf8"));
+    return extractVersionField(readFileSync47(path, "utf8"));
   } catch {
     return null;
   }
@@ -15993,10 +16284,10 @@ function extractVersionField(contents) {
   return match?.[1] ?? null;
 }
 function readFossil(cwd) {
-  const path = join68(cwd, CORE_VERSION_FILE);
+  const path = join69(cwd, CORE_VERSION_FILE);
   if (!existsSync57(path)) return null;
   try {
-    const value = readFileSync46(path, "utf8").trim();
+    const value = readFileSync47(path, "utf8").trim();
     return value === "" ? null : value;
   } catch {
     return null;
@@ -16526,11 +16817,11 @@ import { Command as Command27 } from "commander";
 
 // src/lib/packaged-scripts.ts
 import { existsSync as existsSync58 } from "fs";
-import { dirname as dirname11, join as join69 } from "path";
+import { dirname as dirname11, join as join70 } from "path";
 function findPackagedScript(startDir, relativePath) {
   let dir = startDir;
   for (; ; ) {
-    const candidate = join69(dir, relativePath);
+    const candidate = join70(dir, relativePath);
     if (existsSync58(candidate)) return candidate;
     const parent = dirname11(dir);
     if (parent === dir) return null;

package/package.json

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

package/scripts/verify.sh

@@ -1449,6 +1449,7 @@ if [ -f scripts/biffo.sh ]; then
   run_check plugin-tool-supply sh scripts/biffo.sh check plugin-tool-supply
   run_check core-direct-paths sh scripts/biffo.sh check core-direct-paths
   run_check orphan-ratchet sh scripts/biffo.sh check orphan-ratchet
+  run_check ownership-header-claim sh scripts/biffo.sh check ownership-header-claim
   # #1714 second remediation: the INSTANCE-mode caller, distinct from the
   # self-check above. It clones a real template tree pinned to
   # biffo.core.json's own version and compares against it -- but this repo