@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.1

package/scripts/build/copy-tenant-assets.mjs

@@ -31,10 +31,11 @@
  * reference files that don't exist. The Worker-plane build never sets this, so
  * R2 shadowing semantics are unchanged there.
  */
-import { cp, mkdir, readdir, rm } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { cp, mkdir, rm } from "node:fs/promises";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { listTenantDirIds, tenantDirSegments } from "../lib/tenant-dirs.mjs";
 
 const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const src = resolve(repoRoot, "tenants");
@@ -53,15 +54,21 @@ const versionedEnv = new Set(
     .filter(Boolean),
 );
 const bakeVersioned = process.env.TENANT_ASSETS_BAKE_VERSIONED === "1";
+const tenantDir = (id) => join(repoRoot, ...tenantDirSegments(id));
 const isVersioned = (id) =>
   !bakeVersioned &&
   (versionedEnv.has(id) ||
-    existsSync(join(src, id, ".tot", "assets-versioned")));
+    existsSync(join(tenantDir(id), ".tot", "assets-versioned")));
+
+// Both tiers: real tenants directly under tenants/, platform test tenants one
+// level deeper under tenants/e2e/. The destination stays FLAT — the served URL
+// is `/tenants/<id>/…` for every tenant, whichever tier its source sits in.
+const ids = listTenantDirIds(src, readdirSync, (p) => statSync(p).isDirectory(), join);
 
 let copied = 0;
 let skipped = 0;
-for (const id of await readdir(src)) {
-  const pub = join(src, id, "public");
+for (const id of ids) {
+  const pub = join(tenantDir(id), "public");
   if (!existsSync(pub)) continue;
   // Versioned tenants are served from R2 — baking would shadow the R2 route.
   if (isVersioned(id)) {

package/scripts/dev/ai-edit.mjs

@@ -24,12 +24,13 @@ import { join, dirname } from "node:path";
 import { createMcpClient } from "../../packages/cli/src/mcp.mjs";
 import { resolveDeveloperSession, AuthUnavailableError } from "../../packages/cli/src/auth.mjs";
 import { applyUnifiedDiff } from "./unified-diff.mjs";
+import { tenantDirSegments } from "../lib/tenant-dirs.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
 /** Where a tenant's editable files + AI-edit history live (monorepo layout). */
 export function tenantPaths(repoRoot, tenantId) {
-  const dir = join(repoRoot, "tenants", tenantId);
+  const dir = join(repoRoot, ...tenantDirSegments(tenantId));
   return {
     dir,
     home: join(dir, "content", "home.html"),

package/scripts/dev/file-browser.mjs

@@ -109,8 +109,8 @@ export function readFile(sourceRoot, relPath) {
   }
 
   const norm = relPath.split(sep).join("/");
-  // The viewer needs the on-disk version (C6 baseVersion) + whether the file is in
-  // the write allowlist (C5 editable vs read-only) — surfaced on every ok read.
+  // The viewer needs the on-disk version (baseVersion) + whether the file is in
+  // the write allowlist (editable vs read-only) — surfaced on every ok read.
   const mtimeMs = st.mtimeMs;
   const writable = matchesWriteAllowlist(norm);
   if (BINARY_EXT.has(extname(norm).toLowerCase())) {

package/scripts/dev/file-writer.mjs

@@ -15,7 +15,7 @@
  * lands on disk (and C1's Monitor timestamps the save→reload) — this module never
  * sends its own reload.
  *
- * Stale-write guard (C6): writeSourceFile/handleWrite accept an optional
+ * Stale-write guard: writeSourceFile/handleWrite accept an optional
  * baseVersion — the mtimeMs the client captured when it opened or last saved the
  * file. If the file on disk has since changed (someone edited it via $EDITOR, git,
  * or the AI ask box while autosave was armed), the write is refused with
@@ -74,7 +74,7 @@ export function writeSourceFile(sourceRoot, relPath, content, opts = {}) {
   } catch {
     /* leaf doesn't exist yet — a new file, which is fine */
   }
-  // Stale-write guard (C6): if the client supplied the version it last saw and the
+  // Stale-write guard: if the client supplied the version it last saw and the
   // file has since changed on disk (or now exists when it expected none), refuse
   // rather than clobber. Omit baseVersion to force-save.
   const baseVersion = opts && opts.baseVersion;

package/scripts/dev/integration-guardrails.mjs

@@ -0,0 +1,498 @@
+/**
+ * integration-guardrails.mjs — make the epic's integration discipline routine and
+ * VISIBLE before a unit branch is folded into the umbrella. One command answers
+ * the four questions the lead integrator otherwise asks (and hand-writes a note
+ * about) for every unit:
+ *
+ *   1. Ownership   — does this branch only touch files inside its declared area,
+ *                    or did it wander into files another in-flight unit owns?
+ *   2. Base drift  — has the umbrella moved far enough ahead of this branch's
+ *                    merge-base that a refresh/rebase is due before folding?
+ *   3. Sibling     — do any files this branch touches ALSO appear on a concurrent
+ *      overlap        issue/ fix/ wip/ impl/ branch (a hot-file collision, e.g.
+ *                     the admin Publish module the whole epic keeps colliding on)?
+ *   4. Focused     — do the scoped lint/typecheck/test commands for the touched
+ *      checks         files actually PASS (not just "did you run something")?
+ *
+ * It then prints a structured **integrator handoff note** (files touched grouped
+ * by area, drift status, overlaps, check results) that the lead can paste straight
+ * into an integration commit/PR instead of composing by hand.
+ *
+ * Design mirrors scripts/preview/*-doctor.sh: findings are ordered so the FIRST
+ * ✗ (blocker) or ⚠ (warning) is the thing to deal with, each carries its remedy,
+ * and the exit code is non-zero when a blocker (a failed focused check) is present
+ * so it is safe to drop into a pre-fold gate.
+ *
+ * The git/exec-driven parts live in `main()`; everything checkable — glob→area
+ * matching, drift classification, sibling-overlap join, check derivation, note
+ * formatting — is a pure exported function with no I/O so it unit-tests under
+ * `node --test` (the scripts/dev convention), with no build step and no deps
+ * beyond node: builtins + the `git` CLI.
+ *
+ * Ownership convention: a branch's area is a list of path globs, declared either
+ *   • inline:  --area 'scripts/dev/**' --area 'docs/dev/**'   (repeatable), or
+ *   • in a manifest `.tot-ownership.json` at the repo root, keyed by branch name:
+ *       { "areas": { "issue/integration-conflict-guardrails": ["scripts/dev/**"] } }
+ * With no area declared the ownership check is SKIPPED (reported as such) — it
+ * never fabricates a verdict it can't back.
+ *
+ * Usage:
+ *   node scripts/dev/integration-guardrails.mjs [--umbrella <ref>] [--area <glob>]...
+ *       [--manifest <path>] [--no-siblings] [--no-checks] [--json]
+ *   # defaults: --umbrella feature/8500-storefront-integration, manifest .tot-ownership.json
+ */
+import { execFileSync } from "node:child_process";
+
+/** Umbrella branch this epic folds into. */
+export const DEFAULT_UMBRELLA = "feature/8500-storefront-integration";
+
+/** Branch-name prefixes that denote a concurrent, in-flight unit. */
+export const UNIT_BRANCH_PREFIXES = ["issue/", "fix/", "wip/", "impl/"];
+
+/**
+ * Compile a path glob to a RegExp. Supports `**` (any chars incl. `/`), `*`
+ * (any chars except `/`), and a trailing `/` as shorthand for a directory prefix
+ * (`scripts/dev/` ≡ `scripts/dev/**`). All other regex metacharacters are escaped.
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+export function globToRegExp(glob) {
+  let g = String(glob).replace(/^\.\//, "");
+  if (g.endsWith("/")) g += "**";
+  let re = "";
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i];
+    if (c === "*") {
+      if (g[i + 1] === "*") {
+        re += ".*";
+        i++;
+      } else {
+        re += "[^/]*";
+      }
+    } else if ("\\^$.|?+()[]{}".includes(c)) {
+      re += "\\" + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp("^" + re + "$");
+}
+
+/**
+ * True iff `file` (a posix repo-relative path) matches any of `globs`.
+ * @param {string} file
+ * @param {string[]} globs
+ * @returns {boolean}
+ */
+export function matchesAny(file, globs) {
+  const norm = String(file).replace(/^\.\//, "");
+  return (globs || []).some((g) => globToRegExp(g).test(norm));
+}
+
+/**
+ * Partition touched files into those inside the declared ownership area and those
+ * outside it (cross-area edits that warrant integrator review).
+ * @param {string[]} files
+ * @param {string[]} areaGlobs
+ * @returns {{ declared: boolean, inArea: string[], crossArea: string[] }}
+ */
+export function classifyOwnership(files, areaGlobs) {
+  const declared = Array.isArray(areaGlobs) && areaGlobs.length > 0;
+  if (!declared) return { declared: false, inArea: [...(files || [])], crossArea: [] };
+  const inArea = [];
+  const crossArea = [];
+  for (const f of files || []) {
+    if (matchesAny(f, areaGlobs)) inArea.push(f);
+    else crossArea.push(f);
+  }
+  return { declared: true, inArea, crossArea };
+}
+
+/**
+ * Classify how stale a branch's base is from the count of umbrella commits landed
+ * since the branch's merge-base. `warn` recommends a refresh; `stale` strongly
+ * recommends one before folding.
+ * @param {number} behind  umbrella commits ahead of the merge-base
+ * @param {{ warnAt?: number, staleAt?: number }} [opts]
+ * @returns {{ level: "fresh"|"warn"|"stale", behind: number, recommend: string }}
+ */
+export function classifyBaseDrift(behind, opts = {}) {
+  const warnAt = opts.warnAt ?? 10;
+  const staleAt = opts.staleAt ?? 30;
+  const n = Number.isFinite(behind) ? behind : 0;
+  if (n >= staleAt) {
+    return {
+      level: "stale",
+      behind: n,
+      recommend: `umbrella is ${n} commits ahead of this branch's base — refresh before folding (git merge ${DEFAULT_UMBRELLA}, or rebase) so conflicts surface here, not in the integrator's fold`,
+    };
+  }
+  if (n >= warnAt) {
+    return {
+      level: "warn",
+      behind: n,
+      recommend: `umbrella is ${n} commits ahead — a refresh (git merge ${DEFAULT_UMBRELLA}) is recommended before folding`,
+    };
+  }
+  return { level: "fresh", behind: n, recommend: "base is fresh — no refresh needed" };
+}
+
+/**
+ * Join this branch's touched files against each sibling branch's touched files,
+ * returning the files that appear on at least one sibling (hot-file collisions).
+ * @param {string[]} ourFiles
+ * @param {Record<string, string[]>} siblingFilesByBranch
+ * @returns {Array<{ file: string, branches: string[] }>}
+ */
+export function computeSiblingOverlaps(ourFiles, siblingFilesByBranch) {
+  const ours = new Set(ourFiles || []);
+  /** @type {Map<string, string[]>} */
+  const hits = new Map();
+  for (const [branch, files] of Object.entries(siblingFilesByBranch || {})) {
+    for (const f of files || []) {
+      if (!ours.has(f)) continue;
+      const list = hits.get(f) || [];
+      if (!list.includes(branch)) list.push(branch);
+      hits.set(f, list);
+    }
+  }
+  return [...hits.entries()]
+    .map(([file, branches]) => ({ file, branches: branches.sort() }))
+    .sort((a, b) => a.file.localeCompare(b.file));
+}
+
+/**
+ * Derive the focused check commands implied by a set of touched files — scoped to
+ * what changed rather than the whole `pnpm run check`. Pure/deterministic so the
+ * mapping is unit-tested; the runner in `main()` executes each returned command.
+ *
+ *  • touched `scripts/**` (or storefront dev-plugins/integrations) `*.test.mjs`,
+ *    plus the `.test.mjs` sibling of any touched non-test `.mjs`, → one `node --test`
+ *    over exactly those files.
+ *  • touched `scripts/**` `.mjs`/`.js` → `typecheck:scripts` (checkJs over scripts/).
+ *  • touched `apps/storefront/src/**` `.ts`/`.astro`/`.tsx` → the storefront package typecheck.
+ *
+ * @param {string[]} files
+ * @param {(p: string) => boolean} [existsFn]  whether a repo-relative path exists (for the .test.mjs sibling probe); defaults to always-true
+ * @returns {Array<{ name: string, command: string, args: string[] }>}
+ */
+export function deriveChecks(files, existsFn) {
+  const has = typeof existsFn === "function" ? existsFn : () => true;
+  const list = files || [];
+  const isScript = (f) => /^scripts\//.test(f) || /^apps\/storefront\/(dev-plugins|integrations)\//.test(f);
+
+  /** @type {Set<string>} */
+  const testFiles = new Set();
+  for (const f of list) {
+    if (!isScript(f)) continue;
+    if (f.endsWith(".test.mjs")) {
+      testFiles.add(f);
+    } else if (f.endsWith(".mjs") || f.endsWith(".js")) {
+      const sibling = f.replace(/\.(mjs|js)$/, ".test.mjs");
+      if (has(sibling)) testFiles.add(sibling);
+    }
+  }
+
+  /** @type {Array<{ name: string, command: string, args: string[] }>} */
+  const checks = [];
+  if (testFiles.size > 0) {
+    checks.push({ name: "dev-script tests", command: "node", args: ["--test", ...[...testFiles].sort()] });
+  }
+  if (list.some((f) => /^scripts\/.*\.(mjs|js)$/.test(f))) {
+    checks.push({ name: "scripts typecheck", command: "pnpm", args: ["run", "typecheck:scripts"] });
+  }
+  if (list.some((f) => /^apps\/storefront\/src\/.*\.(ts|tsx|astro)$/.test(f))) {
+    checks.push({ name: "storefront typecheck", command: "pnpm", args: ["--filter", "@tot/storefront", "typecheck"] });
+  }
+  return checks;
+}
+
+/**
+ * @typedef {Object} GuardrailResult
+ * @property {string} branch
+ * @property {string} umbrella
+ * @property {string} mergeBase
+ * @property {string[]} files
+ * @property {{ level: "fresh"|"warn"|"stale", behind: number, recommend: string }} drift
+ * @property {{ declared: boolean, inArea: string[], crossArea: string[] }} ownership
+ * @property {Array<{ file: string, branches: string[] }>} overlaps
+ * @property {Array<{ name: string, ok: boolean, skipped?: boolean, detail?: string }>} checks
+ */
+
+/**
+ * Render the integrator handoff note (markdown) from a result. This is the note
+ * the lead otherwise writes by hand when folding a unit.
+ * @param {GuardrailResult} r
+ * @returns {string}
+ */
+export function formatHandoffNote(r) {
+  const lines = [];
+  lines.push(`### Integration handoff — ${r.branch}`);
+  lines.push("");
+  lines.push(`- **Umbrella:** ${r.umbrella} (merge-base ${short(r.mergeBase)})`);
+  lines.push(`- **Base drift:** ${r.drift.level} (${r.drift.behind} commit(s) behind umbrella)`);
+
+  const own = r.ownership;
+  if (!own.declared) {
+    lines.push(`- **Ownership:** not declared — ${r.files.length} file(s) touched, area unverified`);
+  } else {
+    lines.push(
+      `- **Ownership:** ${own.inArea.length} in-area, ${own.crossArea.length} cross-area` +
+        (own.crossArea.length ? ` ⚠ (${own.crossArea.join(", ")})` : ""),
+    );
+  }
+
+  if (r.overlaps.length) {
+    lines.push(`- **Hot-file overlap:** ${r.overlaps.length} file(s) also on sibling branches ⚠`);
+    for (const o of r.overlaps) lines.push(`    - \`${o.file}\` ↔ ${o.branches.join(", ")}`);
+  } else {
+    lines.push(`- **Hot-file overlap:** none`);
+  }
+
+  if (r.checks.length) {
+    const parts = r.checks.map((c) => `${c.skipped ? "skipped" : c.ok ? "✓" : "✗"} ${c.name}`);
+    lines.push(`- **Focused checks:** ${parts.join(", ")}`);
+  } else {
+    lines.push(`- **Focused checks:** none derived (no checkable files touched)`);
+  }
+
+  lines.push("");
+  lines.push(`**Files touched (${r.files.length}):**`);
+  for (const f of r.files) {
+    const tag = own.declared && own.crossArea.includes(f) ? " ⚠ cross-area" : "";
+    lines.push(`- \`${f}\`${tag}`);
+  }
+  return lines.join("\n");
+}
+
+/** @param {string} sha */
+function short(sha) {
+  return String(sha || "").slice(0, 9);
+}
+
+// ─── git-driven CLI (not covered by unit tests — the pure logic above is) ─────
+
+/** Run git in the repo; returns trimmed stdout, or "" on failure. @param {string[]} args */
+function git(args) {
+  try {
+    return execFileSync("git", args, { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Resolve the umbrella ref to fold against. A worktree's LOCAL umbrella branch is
+ * routinely behind what was last fetched, so prefer `origin/<ref>` when it exists
+ * and is not behind the local ref. If `ref` already names a remote/explicit rev,
+ * it is used as-is.
+ * @param {string} ref
+ * @returns {string}
+ */
+function resolveUmbrella(ref) {
+  if (ref.includes("/") && git(["rev-parse", "--verify", "--quiet", ref])) {
+    // already a remote-tracking or fully-qualified ref the caller chose
+    if (ref.startsWith("origin/") || ref.startsWith("refs/")) return ref;
+  }
+  const remote = `origin/${ref}`;
+  const remoteSha = git(["rev-parse", "--verify", "--quiet", remote]);
+  const localSha = git(["rev-parse", "--verify", "--quiet", ref]);
+  if (!remoteSha) return ref; // no remote-tracking ref — use whatever we were given
+  if (!localSha) return remote;
+  // Use the remote unless the local ref is strictly ahead of it (local has commits
+  // origin lacks — e.g. an integrator working locally ahead of a push).
+  const localAhead = Number(git(["rev-list", "--count", `${remote}..${localSha}`]) || "0");
+  return localAhead > 0 ? ref : remote;
+}
+
+/**
+ * Union of the files this unit changes: commits since the umbrella merge-base,
+ * plus working-tree changes vs HEAD (staged + unstaged), plus untracked files.
+ * Uses prefix-free plumbing (`diff --name-only`, `ls-files --others`) rather than
+ * `status --porcelain` so there is no status-column slicing to get wrong.
+ * @param {string} base
+ * @returns {string[]}
+ */
+function touchedFiles(base) {
+  const set = new Set();
+  const add = (out) => {
+    for (const l of out.split("\n")) if (l.trim()) set.add(l.trim());
+  };
+  if (base) add(git(["diff", "--name-only", `${base}..HEAD`]));
+  add(git(["diff", "--name-only", "HEAD"])); // staged + unstaged vs HEAD
+  add(git(["ls-files", "--others", "--exclude-standard"])); // untracked
+  return [...set].sort();
+}
+
+/** @param {string} branch @param {string} umbrella */
+function branchTouchedFiles(branch, umbrella) {
+  const base = git(["merge-base", branch, umbrella]);
+  if (!base) return [];
+  const out = git(["diff", "--name-only", `${base}..${branch}`]);
+  return out ? out.split("\n").filter(Boolean) : [];
+}
+
+/** @param {string[]} argv */
+function parseArgs(argv) {
+  const opts = {
+    umbrella: DEFAULT_UMBRELLA,
+    areas: /** @type {string[]} */ ([]),
+    manifest: ".tot-ownership.json",
+    siblings: true,
+    checks: true,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--umbrella") opts.umbrella = argv[++i];
+    else if (a === "--area") opts.areas.push(argv[++i]);
+    else if (a === "--manifest") opts.manifest = argv[++i];
+    else if (a === "--no-siblings") opts.siblings = false;
+    else if (a === "--no-checks") opts.checks = false;
+    else if (a === "--json") opts.json = true;
+    else if (a === "-h" || a === "--help") opts.help = true;
+    else throw new Error(`unknown argument: ${a}`);
+  }
+  return opts;
+}
+
+async function main() {
+  const { readFileSync, existsSync } = await import("node:fs");
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (e) {
+    process.stderr.write(`${e.message}\n`);
+    process.exit(2);
+    return;
+  }
+  if (opts.help) {
+    process.stdout.write(
+      "usage: node scripts/dev/integration-guardrails.mjs [--umbrella <ref>] [--area <glob>]... " +
+        "[--manifest <path>] [--no-siblings] [--no-checks] [--json]\n",
+    );
+    return;
+  }
+
+  const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]) || "HEAD";
+  // Fold against the SHARED umbrella tip, not a possibly-stale local ref: prefer
+  // origin/<umbrella> when it exists AND is at least as advanced as the local ref
+  // (a local umbrella branch in a worktree is routinely behind what was fetched).
+  const umbrella = resolveUmbrella(opts.umbrella);
+  const mergeBase = git(["merge-base", "HEAD", umbrella]);
+  if (!mergeBase) {
+    process.stderr.write(`✗ no merge-base between HEAD and ${umbrella} — is the umbrella fetched?\n`);
+    process.exit(1);
+    return;
+  }
+  const behind = Number(git(["rev-list", "--count", `${mergeBase}..${umbrella}`]) || "0");
+  const files = touchedFiles(mergeBase);
+
+  // Ownership area: explicit --area wins; else manifest keyed by branch name.
+  let areas = opts.areas;
+  if (areas.length === 0 && existsSync(opts.manifest)) {
+    try {
+      const manifest = JSON.parse(readFileSync(opts.manifest, "utf8"));
+      const declared = manifest && manifest.areas && manifest.areas[branch];
+      if (Array.isArray(declared)) areas = declared;
+    } catch {
+      /* a malformed manifest just means "no declared area" */
+    }
+  }
+
+  const drift = classifyBaseDrift(behind);
+  const ownership = classifyOwnership(files, areas);
+
+  /** @type {Record<string, string[]>} */
+  const siblingFiles = {};
+  if (opts.siblings) {
+    const raw = git(["for-each-ref", "--format=%(refname:short)", "refs/heads"]);
+    for (const b of raw.split("\n").filter(Boolean)) {
+      if (b === branch) continue;
+      if (!UNIT_BRANCH_PREFIXES.some((p) => b.startsWith(p))) continue;
+      const bf = branchTouchedFiles(b, umbrella);
+      if (bf.length) siblingFiles[b] = bf;
+    }
+  }
+  const overlaps = computeSiblingOverlaps(files, siblingFiles);
+
+  /** @type {Array<{ name: string, ok: boolean, skipped?: boolean, detail?: string }>} */
+  const checkResults = [];
+  const derived = deriveChecks(files, (p) => existsSync(p));
+  if (!opts.checks) {
+    for (const c of derived) checkResults.push({ name: c.name, ok: true, skipped: true });
+  } else {
+    for (const c of derived) {
+      try {
+        execFileSync(c.command, c.args, { stdio: "pipe", encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+        checkResults.push({ name: c.name, ok: true });
+      } catch (e) {
+        const tail = String((e && (e.stdout || "")) + (e && (e.stderr || ""))).trim().split("\n").slice(-6).join("\n");
+        checkResults.push({ name: c.name, ok: false, detail: tail });
+      }
+    }
+  }
+
+  /** @type {GuardrailResult} */
+  const result = { branch, umbrella, mergeBase, files, drift, ownership, overlaps, checks: checkResults };
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else {
+    renderReport(result);
+    process.stdout.write("\n" + formatHandoffNote(result) + "\n");
+  }
+
+  const blocker = checkResults.some((c) => !c.ok && !c.skipped);
+  process.exit(blocker ? 1 : 0);
+}
+
+/** @param {GuardrailResult} r */
+function renderReport(r) {
+  const ok = (s) => process.stdout.write(`  ✓ ${s}\n`);
+  const bad = (s) => process.stdout.write(`  ✗ ${s}\n`);
+  const warn = (s) => process.stdout.write(`  ⚠ ${s}\n`);
+  const note = (s) => process.stdout.write(`    → ${s}\n`);
+
+  process.stdout.write(`\n== integration guardrails: ${r.branch} → ${r.umbrella} ==\n`);
+
+  // 1. base drift
+  if (r.drift.level === "fresh") ok(`base fresh (${r.drift.behind} behind umbrella)`);
+  else warn(`base drift: ${r.drift.behind} behind umbrella`), note(r.drift.recommend);
+
+  // 2. ownership
+  if (!r.ownership.declared) {
+    warn(`ownership area not declared for ${r.branch}`);
+    note("declare it in .tot-ownership.json (areas[<branch>]) or pass --area <glob> to enable the check");
+  } else if (r.ownership.crossArea.length === 0) {
+    ok(`ownership clean — all ${r.ownership.inArea.length} touched file(s) inside declared area`);
+  } else {
+    warn(`${r.ownership.crossArea.length} cross-area edit(s) outside declared area`);
+    for (const f of r.ownership.crossArea) note(f);
+    note("confirm these are intended, or move them to their owner's branch before folding");
+  }
+
+  // 3. sibling overlap
+  if (r.overlaps.length === 0) ok("no hot-file overlap with sibling unit branches");
+  else {
+    warn(`${r.overlaps.length} file(s) also touched by concurrent unit branch(es)`);
+    for (const o of r.overlaps) note(`${o.file}  ↔  ${o.branches.join(", ")}`);
+    note("coordinate fold order with the integrator; expect a conflict on these — refresh base first");
+  }
+
+  // 4. focused checks
+  if (r.checks.length === 0) ok("no focused checks derived (no checkable files touched)");
+  for (const c of r.checks) {
+    if (c.skipped) note(`check skipped (--no-checks): ${c.name}`);
+    else if (c.ok) ok(`focused check passed: ${c.name}`);
+    else {
+      bad(`focused check FAILED: ${c.name}`);
+      if (c.detail) for (const l of c.detail.split("\n")) note(l);
+    }
+  }
+}
+
+// Run only when invoked directly (not when imported by the test).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}

package/scripts/dev/safe-path.mjs

@@ -90,8 +90,8 @@ export function isSafePath(root, relPath) {
 }
 
 /**
- * Strict WRITE allowlist for C5's `POST /__tot/write` — only the raw-HTML
- * content surface is writable. Read/tree endpoints (C3) do NOT use this; they
+ * Strict WRITE allowlist for the `POST /__tot/write` endpoint — only the raw-HTML
+ * content surface is writable. Read/tree endpoints do NOT use this; they
  * rely on `resolveSafePath` containment alone so the tree can show everything.
  * Kept here so the write path reuses the one guard rather than reinventing it.
  */

package/scripts/dev/tenant-source-root.mjs

@@ -4,7 +4,7 @@
  *
  * CRITICAL (standalone write-through): in `--workspace` mode `tot dev` COPIES the
  * developer's checkout into an in-tree graft and re-syncs on save. The file tree,
- * viewer, diff and (C5) writer must operate on the developer's REAL CHECKOUT —
+ * viewer, diff and writer must operate on the developer's REAL CHECKOUT —
  * NOT the in-tree graft — or edits made in the browser are silently discarded on
  * the next resync. `tot dev` therefore sets TOT_DEV_SOURCE_ROOT to the checkout
  * in standalone mode and to `tenants/<id>/` in monorepo mode; this module is the
@@ -19,6 +19,7 @@
  */
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { tenantDirSegments } from "../lib/tenant-dirs.mjs";
 
 /**
  * @returns {{ok:true, tenantId:string, sourceRoot:string, gitCwd:string}
@@ -72,5 +73,5 @@ export function resolveTenantSourceRoot(env = process.env) {
 export function resolveDevSourceRoot(workspacePath, repoRoot, tenant) {
   return workspacePath
     ? resolve(workspacePath)
-    : resolve(repoRoot, "tenants", tenant);
+    : resolve(repoRoot, ...tenantDirSegments(tenant));
 }

package/scripts/tot-dev.mjs

@@ -62,6 +62,7 @@ import {
 import { dirname, resolve, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveDevSourceRoot } from "./dev/tenant-source-root.mjs";
+import { tenantDirRelative, tenantDirSegments } from "./lib/tenant-dirs.mjs";
 import { firstFreePort } from "./dev/port-check.mjs";
 import { resync, startWatch } from "./dev/checkout-watch.mjs";
 
@@ -244,7 +245,7 @@ if (workspacePath) {
     // structurally (ignoring any legacy `repo` field in the checkout's .tot/config.json).
     const wsRel = String(map.workspace ?? "").replace(/\/+$/, "");
     if (!wsRel) continue;
-    const repoRel = join("tenants", tenant, wsRel);
+    const repoRel = join(tenantDirRelative(tenant), wsRel);
 
     const source = resolve(wsRoot, wsRel); // real files in the checkout
     const target = resolve(repoRoot, repoRel); // where the app globs them
@@ -288,7 +289,7 @@ if (workspacePath) {
     cleanupGrafts();
     process.exit(1);
   }
-} else if (!existsSync(resolve(repoRoot, "tenants", tenant, "content"))) {
+} else if (!existsSync(resolve(repoRoot, ...tenantDirSegments(tenant), "content"))) {
   console.warn(`⚠ no tenants/${tenant}/content/ found — the tenant may not be registered yet.`);
 }
 
@@ -342,11 +343,11 @@ console.log(`  Private local preview — nothing is published. Server binds all
 // tells Astro "you are already the managed child → run foreground" (see astro's
 // cli/dev/{index,background}.js), so our SIGINT/exit lifecycle and symlink cleanup
 // stay correct. Monorepo mode is left untouched (current behavior).
-// TOT_DEV_TENANT tells the inline-AI edit loop (WS5 G1 — astro.config.mjs's
+// TOT_DEV_TENANT tells the inline-AI edit loop (astro.config.mjs's
 // inlineAiEditPlugin, scripts/dev/ai-edit.mjs) which tenant's content/theme to
 // read+write: one `tot dev <tenant>` run always serves exactly one tenant, so
 // there's no per-request domain lookup to do.
-// TOT_DEV_SOURCE_ROOT tells the /dev file tools (C3 tree/viewer, C4 diff, C5
+// TOT_DEV_SOURCE_ROOT tells the /dev file tools (tree/viewer, diff,
 // writer — scripts/dev/tenant-source-root.mjs) WHERE the developer's editable
 // source lives. STANDALONE: the developer's REAL checkout (wsRoot) — the tools
 // MUST read+write it, NOT the in-tree graft, or browser edits are silently lost