create-ailk 0.23.0 → 0.25.1

package/templates/tools/lint-architecture.ts

@@ -13,7 +13,34 @@
  *   - the global and per-app `forbidden_patterns` (with `paths_excluded`);
  *   - the `namespaces` boundaries inside `database/`, when declared:
  *     cross-namespace relative imports and cross-namespace Prisma `@relation`
- *     directives.
+ *     directives;
+ *   - the `upgradeable_consumer` rules, when declared — this site builds on
+ *     the published `@working-theory/*` packages and never forks them:
+ *     every `pnpm-workspace.yaml` glob is inside the declared `workspaces`;
+ *     no `package.json` outside `node_modules` takes an in-scope name the
+ *     scaffold did not create (`scaffold_packages`); no `patchedDependencies`
+ *     entry (root `package.json` `pnpm` block or `pnpm-workspace.yaml`)
+ *     patches an in-scope package; and every declaration of one in-scope
+ *     package (dependencies, devDependencies, peerDependencies,
+ *     optionalDependencies, `pnpm.overrides`, `resolutions`, workspace
+ *     `overrides`) uses the same caret range;
+ *   - the `customizations` rules, when declared (#9223) — every code file
+ *     under `apps/` the scaffold did not ship maps to an entry in
+ *     `customizations.yaml` recording its request and its build-in decision:
+ *     a file in neither `.ailk-template-files.json` nor `scaffold_paths` and
+ *     matched by no entry is refused; an `undecided` entry passes only while
+ *     `undecided_ok_until` is in the future; a `build-in: ailk#N` entry whose
+ *     paths still match the site's own test files is refused (tests belong
+ *     in AILK); a malformed or missing manifest is refused naming the field.
+ *     With no template record the lint warns and skips the file rules;
+ *   - the shadow-copy rule (#9201), under the same block and record — a
+ *     site-authored file under `apps/` most of whose substantive lines are a
+ *     module's that an installed `@working-theory/*` package ships (found
+ *     through its export map) is a copy, edited or not, and is refused naming
+ *     the file and the `<package>/<subpath>` module it shadows; a wrapper that
+ *     imports and re-exports or composes the module passes. An installed
+ *     package that is one of this site's own workspaces (`apps/*`, `database`
+ *     — pnpm may hoist one) is its source, not a shipped module (#9558).
  *
  * An import target is checked only when it is a workspace present in this
  * repo (`apps/*`, `database`); `@working-theory/*` libraries install from npm
@@ -21,16 +48,30 @@
  *
  * Usage:
  *   pnpm architecture            # or: tsx tools/lint-architecture.ts
+ *   tsx tools/lint-architecture.ts --seed-customizations
+ *                                # print the customizations.yaml entries an
+ *                                # existing site needs (undecided); writes nothing
+ *   tsx tools/lint-architecture.ts --verbose
+ *                                # also warn which installed packages the
+ *                                # shadow-copy check skipped as this site's own
  *
  * Exit codes:
  *   0 — no violations
  *   1 — violations found (each names the file, the line and the rule)
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 
-import { parse as parseYaml } from "yaml";
+import {
+  isMap,
+  isScalar,
+  isSeq,
+  LineCounter,
+  parse as parseYaml,
+  parseDocument,
+  type Node,
+} from "yaml";
 
 interface ForbiddenPattern {
   pattern: string;
@@ -45,10 +86,23 @@ interface AppRule {
   forbidden_patterns?: ForbiddenPattern[];
 }
 
+interface UpgradeableConsumer {
+  package_scope?: string;
+  workspaces?: string[];
+  scaffold_packages?: string[];
+}
+
+interface Customizations {
+  manifest?: string;
+  scaffold_paths?: string[];
+}
+
 interface ArchConfig {
   apps?: Record<string, AppRule>;
   forbidden_patterns?: ForbiddenPattern[];
   namespaces?: { members?: Record<string, { path: string }> };
+  upgradeable_consumer?: UpgradeableConsumer;
+  customizations?: Customizations;
 }
 
 interface Violation {
@@ -60,6 +114,9 @@ interface Violation {
 
 const ROOT = resolve(dirname(process.argv[1] ?? "."), "..");
 const SKIP_DIRS = new Set([
+  ".git",
+  ".pnpm-store",
+  ".vercel",
   "node_modules",
   "dist",
   ".next",
@@ -81,12 +138,12 @@ function rel(abs: string): string {
   return toPosix(relative(ROOT, abs));
 }
 
-function walk(dir: string, match: RegExp, out: string[] = []): string[] {
+function walk(dir: string, match: RegExp, out: string[] = [], skip = SKIP_DIRS): string[] {
   if (!existsSync(dir)) return out;
-  for (const entry of readdirSync(dir)) {
-    if (SKIP_DIRS.has(entry)) continue;
+  for (const entry of readdirSync(dir).sort()) {
+    if (skip.has(entry)) continue;
     const p = join(dir, entry);
-    if (statSync(p).isDirectory()) walk(p, match, out);
+    if (statSync(p).isDirectory()) walk(p, match, out, skip);
     else if (match.test(entry) && !entry.endsWith(".d.ts")) out.push(p);
   }
   return out;
@@ -266,6 +323,691 @@ function checkNamespaces(cfg: ArchConfig): Violation[] {
   return out;
 }
 
+// ── Upgradeable consumer (#9191) ─────────────────────────────────────────
+//
+// A copied, patched or pinned-off package stops taking upstream fixes, and
+// whoever made the copy believes it is harmless. These rules refuse each form.
+
+interface PackageJson {
+  name?: unknown;
+  pnpm?: { patchedDependencies?: unknown; overrides?: unknown };
+  resolutions?: unknown;
+  [field: string]: unknown;
+}
+
+interface Declaration {
+  file: string;
+  line: number;
+  name: string;
+  range: string;
+  field: string;
+}
+
+const DEP_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+] as const;
+const CARET_RANGE = /^\^\d+(?:\.\d+){0,2}(?:-[0-9A-Za-z.-]+)?$/;
+
+/** The 1-based line of the first line containing `needle`, else 1. */
+function lineOfText(text: string, needle: string): number {
+  const i = text.split("\n").findIndex((line) => line.includes(needle));
+  return i === -1 ? 1 : i + 1;
+}
+
+/**
+ * The 1-based line of `key` as a map key at or after the first line holding
+ * `section` (a field label), so a package declared in two fields of one file
+ * reports each at its own line. Falls back to the first mention of `key`.
+ */
+function lineOfKey(text: string, section: string, key: string): number {
+  const lines = text.split("\n");
+  const start = Math.max(0, lines.findIndex((line) => line.includes(section)));
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const keyRe = new RegExp(`(?:^|[\\s{,])["']?${escaped}["']?\\s*:`);
+  const i = lines.findIndex((line, n) => n >= start && keyRe.test(line));
+  return i === -1 ? lineOfText(text, key) : i + 1;
+}
+
+/** A map-valued field as string entries, or none. */
+function stringEntries(value: unknown): [string, string][] {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+  return Object.entries(value).filter(
+    (e): e is [string, string] => typeof e[1] === "string",
+  );
+}
+
+/** A patch or override key (`@s/p@1.2.3`, `a>@s/p@^1`) → the package it targets. */
+function packageOfKey(key: string): string {
+  const target = key.slice(key.lastIndexOf(">") + 1);
+  const at = target.lastIndexOf("@");
+  return at > 0 ? target.slice(0, at) : target;
+}
+
+/** True when `glob` reaches nothing outside one of the `allowed` workspace globs. */
+function insideWorkspaces(glob: string, allowed: string[]): boolean {
+  const g = glob.replace(/^\.\//, "").replace(/\/$/, "");
+  return allowed.some((a) => {
+    if (g === a) return true;
+    if (!a.endsWith("/*")) return false;
+    const prefix = a.slice(0, -1);
+    const rest = g.slice(prefix.length);
+    return g.startsWith(prefix) && rest !== "" && !rest.includes("/") && !rest.includes("**");
+  });
+}
+
+function checkUpgradeableConsumer(cfg: ArchConfig): Violation[] {
+  const uc = cfg.upgradeable_consumer;
+  if (!uc) return [];
+  const scope = uc.package_scope ?? "@working-theory/";
+  const workspaces = uc.workspaces ?? [];
+  const created = new Set(uc.scaffold_packages ?? []);
+  const inScope = (name: string) => name.startsWith(scope);
+  const out: Violation[] = [];
+  const decls: Declaration[] = [];
+
+  const patches = (file: string, text: string, value: unknown) => {
+    for (const [key] of stringEntries(value)) {
+      if (!inScope(packageOfKey(key))) continue;
+      out.push({
+        file,
+        line: lineOfKey(text, "patchedDependencies", key),
+        rule: `patchedDependencies patches "${key}"`,
+        reason:
+          "Fix: remove the patch — a patched package stops taking upstream fixes. Wrap or configure it from your app, or report the defect upstream.",
+      });
+    }
+  };
+  const declare = (file: string, text: string, field: string, value: unknown, byKey: boolean) => {
+    for (const [key, range] of stringEntries(value)) {
+      const name = byKey ? packageOfKey(key) : key;
+      if (!inScope(name)) continue;
+      // A scaffold's own workspace may be linked locally; anything else may not.
+      if (created.has(name) && range.startsWith("workspace:")) continue;
+      const line = lineOfKey(text, field.slice(field.lastIndexOf(".") + 1), key);
+      decls.push({ file, line, name, range, field });
+    }
+  };
+
+  const wsPath = join(ROOT, "pnpm-workspace.yaml");
+  if (existsSync(wsPath)) {
+    const text = readFileSync(wsPath, "utf8");
+    const ws = (parseYaml(text) ?? {}) as {
+      packages?: unknown;
+      patchedDependencies?: unknown;
+      overrides?: unknown;
+    };
+    for (const glob of Array.isArray(ws.packages) ? ws.packages : []) {
+      if (typeof glob !== "string" || glob.startsWith("!")) continue;
+      if (insideWorkspaces(glob, workspaces)) continue;
+      out.push({
+        file: wsPath,
+        line: lineOfText(text, glob),
+        rule: `workspace glob "${glob}" is outside this site's workspaces (${workspaces.join(", ")})`,
+        reason: `Fix: remove it. A site consumes ${scope}* from npm — compose, wrap or configure the published package from an app instead of keeping a local package tree.`,
+      });
+    }
+    patches(wsPath, text, ws.patchedDependencies);
+    declare(wsPath, text, "overrides", ws.overrides, true);
+  }
+
+  for (const file of walk(ROOT, /^package\.json$/)) {
+    const text = readFileSync(file, "utf8");
+    let pkg: PackageJson;
+    try {
+      pkg = JSON.parse(text) as PackageJson;
+    } catch {
+      continue; // pnpm itself refuses an unparseable manifest
+    }
+    if (typeof pkg.name === "string" && inScope(pkg.name) && !created.has(pkg.name)) {
+      out.push({
+        file,
+        line: lineOfText(text, `"${pkg.name}"`),
+        rule: `local package named "${pkg.name}" — not a package this scaffold created (${[...created].join(", ")})`,
+        reason: `Fix: delete the local copy and depend on the published ${pkg.name}; build on it by composing, wrapping or configuring it through its documented extension points — never copy it out of node_modules.`,
+      });
+    }
+    for (const field of DEP_FIELDS) declare(file, text, field, pkg[field], false);
+    declare(file, text, "pnpm.overrides", pkg.pnpm?.overrides, true);
+    declare(file, text, "resolutions", pkg.resolutions, true);
+    patches(file, text, pkg.pnpm?.patchedDependencies);
+  }
+
+  const byName = new Map<string, Declaration[]>();
+  for (const d of decls) {
+    if (!CARET_RANGE.test(d.range)) {
+      const example = /^\d/.test(d.range) ? `^${d.range}` : "^<version>";
+      out.push({
+        file: d.file,
+        line: d.line,
+        rule: `${d.name} is "${d.range}" in ${d.field}, not a caret range`,
+        reason: `Fix: declare it as a caret range (e.g. "${example}") so upgrades flow; never pin it, link it or point it at a local copy.`,
+      });
+      continue;
+    }
+    const list = byName.get(d.name) ?? [];
+    list.push(d);
+    byName.set(d.name, list);
+  }
+  for (const [name, list] of byName) {
+    if (new Set(list.map((d) => d.range)).size < 2) continue;
+    const where = list.map((d) => `${rel(d.file)} ${d.field} "${d.range}"`).join(", ");
+    for (const d of list) {
+      out.push({
+        file: d.file,
+        line: d.line,
+        rule: `${name} is declared on different ranges: ${where}`,
+        reason: `Fix: align every declaration of ${name} on one caret range.`,
+      });
+    }
+  }
+  return out;
+}
+
+// ── Customizations manifest (#9223) ──────────────────────────────────────
+//
+// A customization in a site is the exception: AILK builds it in unless it
+// decides not to, and the decision is recorded next to the code. "Site-
+// authored" is membership only — a code file under `apps/` that is neither a
+// template-record key nor on `scaffold_paths` — never a hash: an edited
+// template file is still the template's.
+
+const MANIFEST_PATH = "customizations.yaml";
+const RECORD_PATH = ".ailk-template-files.json";
+const CODE_FILE_RE = /\.(?:[cm]?[jt]sx?)$/;
+const TEST_FILE_RE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+const ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+const REQUEST_RE = /^([\w.-]+\/[\w.-]+)?#\d+$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const DECISION_AILK = /^build-in: ailk#(\d+)(?: [—-] .+)?$/;
+const DECISION_SITE = /^build-in: site [—-] [^,]+, \d{4}-\d{2}-\d{2}, .+$/;
+const DECISION_GRAMMAR =
+  "undecided | build-in: ailk#<N>[ — <text>] | build-in: site — <decider>, <YYYY-MM-DD>, <reason>";
+const NO_RECORD_WARNING = `architecture: warning — no ${RECORD_PATH}: site-authored files cannot be told from template files; run create-ailk update to write it`;
+
+/** Warnings main() prints to stderr; they never change the exit code. */
+const warnings: string[] = [];
+const VERBOSE = process.argv.includes("--verbose");
+
+interface Entry {
+  id: string;
+  line: number;
+  patterns: RegExp[];
+  decision: string;
+}
+
+/**
+ * A path pattern as a regex: `**` matches zero or more whole segments, `*`
+ * matches within one segment, and every other character is literal — route
+ * segments carry `[locale]` and `(authed)`, so brackets are never syntax.
+ */
+function globToRegExp(glob: string): RegExp {
+  const segments = glob.split("/");
+  let re = "^";
+  segments.forEach((seg, i) => {
+    const last = i === segments.length - 1;
+    if (seg === "**") {
+      re += last ? ".*" : "(?:[^/]+/)*";
+      return;
+    }
+    re += seg.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*");
+    if (!last) re += "/";
+  });
+  return new RegExp(`${re}$`);
+}
+
+function isTestFile(relPath: string): boolean {
+  const segments = relPath.split("/");
+  return segments.includes("__tests__") || TEST_FILE_RE.test(segments[segments.length - 1] ?? "");
+}
+
+/** The template record's file keys, or null when the site has no record. */
+function readRecord(): Set<string> | null {
+  const path = join(ROOT, RECORD_PATH);
+  if (!existsSync(path)) return null;
+  try {
+    const files = (JSON.parse(readFileSync(path, "utf8")) as { files?: unknown }).files;
+    return new Set(files && typeof files === "object" ? Object.keys(files) : []);
+  } catch {
+    return null;
+  }
+}
+
+/** Every site-authored code file under `apps/`, root-relative, sorted. */
+function siteAuthoredFiles(record: Set<string>, scaffoldPaths: string[]): string[] {
+  const shipped = scaffoldPaths.map(globToRegExp);
+  return walk(join(ROOT, "apps"), CODE_FILE_RE)
+    .map(rel)
+    .filter((p) => !record.has(p) && !shipped.some((re) => re.test(p)))
+    .sort();
+}
+
+/**
+ * Parse `customizations.yaml` into entries, pushing one violation per schema
+ * fault, each naming the field. A faulty entry is kept when it has an `id`
+ * and `paths`, so one fault never turns its files into unmatched ones.
+ */
+/** Null when the manifest is missing — the caller reports only that. */
+function readManifest(out: Violation[]): { entries: Entry[]; graceUntil: string | undefined } | null {
+  const file = join(ROOT, MANIFEST_PATH);
+  const entries: Entry[] = [];
+  let graceUntil: string | undefined;
+  if (!existsSync(file)) {
+    out.push({
+      file,
+      line: 1,
+      rule: `no ${MANIFEST_PATH} — architecture.yaml declares customizations`,
+      reason: `Fix: create ${MANIFEST_PATH} at the site root with \`customizations: []\` (copy it from a fresh scaffold).`,
+    });
+    return null;
+  }
+  const text = readFileSync(file, "utf8");
+  const counter = new LineCounter();
+  const doc = parseDocument(text, { lineCounter: counter });
+  const lineOf = (node: Node | null | undefined, fallback = 1): number =>
+    node?.range ? counter.linePos(node.range[0]).line : fallback;
+  const fault = (line: number, rule: string, fix: string) =>
+    out.push({ file, line, rule, reason: `Fix: ${fix}` });
+  if (doc.errors.length > 0) {
+    const err = doc.errors[0]!;
+    fault(err.linePos?.[0]?.line ?? 1, `${MANIFEST_PATH} does not parse: ${err.message.split("\n")[0]}`, "make it valid YAML — copy the shape from a fresh scaffold's customizations.yaml.");
+    return { entries, graceUntil };
+  }
+  const root = doc.contents;
+  if (!isMap(root)) {
+    fault(1, `${MANIFEST_PATH} is not a map`, "the file holds `undecided_ok_until` (optional) and `customizations` (a list).");
+    return { entries, graceUntil };
+  }
+  const scalarText = (node: unknown): string | undefined => {
+    if (!isScalar(node)) return undefined;
+    const v: unknown = node.value;
+    return typeof v === "string" ? v : typeof v === "number" || typeof v === "boolean" ? String(v) : undefined;
+  };
+  let list: unknown;
+  let listLine = 1;
+  for (const pair of root.items) {
+    const key = scalarText(pair.key);
+    const keyLine = lineOf(pair.key as Node);
+    if (key === "undecided_ok_until") {
+      const value = scalarText(pair.value);
+      if (value === undefined || !DATE_RE.test(value) || Number.isNaN(Date.parse(value))) {
+        fault(keyLine, `undecided_ok_until ${JSON.stringify(value ?? null)} is not a YYYY-MM-DD date`, "write it as YYYY-MM-DD, e.g. undecided_ok_until: 2027-01-31.");
+      } else {
+        graceUntil = value;
+      }
+    } else if (key === "customizations") {
+      list = pair.value;
+      listLine = keyLine;
+    } else {
+      fault(keyLine, `unknown key ${JSON.stringify(key)} — the keys are undecided_ok_until and customizations`, "remove it, or move it under the entry it describes.");
+    }
+  }
+  if (list === undefined) {
+    fault(1, "customizations is required (a list; [] when the site has none)", "add `customizations: []`.");
+    return { entries, graceUntil };
+  }
+  if (!isSeq(list)) {
+    fault(lineOf(list as Node, listLine), "customizations is not a list", "write `customizations: []` or a sequence of entries (- id: … / paths: … / request: … / decision: …).");
+    return { entries, graceUntil };
+  }
+  const seen = new Set<string>();
+  list.items.forEach((item, index) => {
+    if (!isMap(item)) {
+      fault(lineOf(item as Node), `customizations[${index}] is not a map`, "an entry is a map with id, paths, request and decision.");
+      return;
+    }
+    const line = lineOf(item);
+    const fields = new Map<string, unknown>();
+    for (const pair of item.items) {
+      const key = scalarText(pair.key) ?? "";
+      if (["id", "paths", "request", "decision"].includes(key)) fields.set(key, pair.value);
+      else fault(lineOf(pair.key as Node, line), `unknown key ${JSON.stringify(key)} — an entry's keys are id, paths, request, decision`, "remove it.");
+    }
+    const id = scalarText(fields.get("id"));
+    if (!fields.has("id")) fault(line, "id is required on every entry", "give the entry a short kebab-case id, e.g. booking-embed.");
+    else if (id === undefined || !ID_RE.test(id)) fault(lineOf(fields.get("id") as Node, line), `id ${JSON.stringify(id ?? null)} is not /^[a-z0-9][a-z0-9-]*$/`, "use lowercase letters, digits and hyphens.");
+    else if (seen.has(id)) fault(lineOf(fields.get("id") as Node, line), `duplicate id ${JSON.stringify(id)}`, "every entry's id is unique; merge the two entries or rename one.");
+    else seen.add(id);
+
+    const patterns: RegExp[] = [];
+    const paths = fields.get("paths");
+    if (!fields.has("paths")) fault(line, "paths is required on every entry", "list the paths (or globs) under apps/ the customization owns.");
+    else if (!isSeq(paths) || paths.items.length === 0) fault(lineOf(paths as Node, line), "paths must be a non-empty list", "list at least one path under apps/.");
+    else {
+      for (const node of paths.items) {
+        const p = scalarText(node);
+        const pLine = lineOf(node as Node, line);
+        if (p === undefined) fault(pLine, "paths entry is not a string", "write each path as a quoted string.");
+        else if (p.includes("\\")) fault(pLine, `paths entry ${JSON.stringify(p)} has a backslash`, "use `/` separators.");
+        else if (!p.startsWith("apps/")) fault(pLine, `paths entry ${JSON.stringify(p)} is outside apps/`, "an entry covers source files under apps/ only.");
+        else if (p.split("/").includes("..")) fault(pLine, `paths entry ${JSON.stringify(p)} has a .. segment`, "write the path from the site root, with no ..");
+        else if (p.split("/").some((s) => s.includes("**") && s !== "**")) fault(pLine, `paths entry ${JSON.stringify(p)} has a ** inside a segment`, "`**` must be a whole segment, e.g. apps/web/lib/**.");
+        else patterns.push(globToRegExp(p));
+      }
+    }
+
+    const decision = scalarText(fields.get("decision"));
+    if (!fields.has("decision")) fault(line, `decision is required on every entry (${DECISION_GRAMMAR})`, "record the build-in decision, or `undecided` while undecided_ok_until is in the future.");
+    else if (decision === undefined || (decision !== "undecided" && ![DECISION_AILK, DECISION_SITE].some((re) => re.test(decision)))) fault(lineOf(fields.get("decision") as Node, line), `decision ${JSON.stringify(decision ?? null)} is not one of: ${DECISION_GRAMMAR}`, "write exactly one of the three forms (the separator is — or -, with a space on each side).");
+
+    const request = scalarText(fields.get("request"));
+    if (fields.has("request") && (request === undefined || !REQUEST_RE.test(request))) fault(lineOf(fields.get("request") as Node, line), `request ${JSON.stringify(request ?? null)} is not <owner/repo>#<N> or #<N>`, "name the issue that requested the customization, e.g. acme/acme-site#12.");
+    else if (!fields.has("request") && decision !== undefined && decision.startsWith("build-in:")) fault(line, "request is required on a build-in: entry", "name the issue that requested the customization, e.g. request: acme/acme-site#12.");
+
+    if (id !== undefined && patterns.length > 0 && decision !== undefined) {
+      entries.push({ id, line, patterns, decision });
+    }
+  });
+  return { entries, graceUntil };
+}
+
+function checkCustomizations(cfg: ArchConfig): Violation[] {
+  const block = cfg.customizations;
+  if (!block) return [];
+  const out: Violation[] = [];
+  const parsed = readManifest(out);
+  if (parsed === null) return out;
+  const { entries, graceUntil } = parsed;
+  const manifest = join(ROOT, MANIFEST_PATH);
+  const today = new Date().toISOString().slice(0, 10);
+
+  // R5b — undecided only inside the grace.
+  for (const e of entries) {
+    if (e.decision !== "undecided") continue;
+    if (graceUntil !== undefined && graceUntil > today) continue;
+    out.push({
+      file: manifest,
+      line: e.line,
+      rule: `customization "${e.id}" is undecided and undecided_ok_until is ${graceUntil === undefined ? "absent" : `${graceUntil}, not in the future`}`,
+      reason:
+        "Fix: record the decision (build-in: ailk#N — AILK builds it in | build-in: site — <decider>, <date>, <reason>), or set undecided_ok_until to a future YYYY-MM-DD while the request is decided.",
+    });
+  }
+
+  const record = readRecord();
+  if (record === null) {
+    warnings.push(NO_RECORD_WARNING);
+    return out;
+  }
+  const authored = siteAuthoredFiles(record, block.scaffold_paths ?? []);
+
+  // R5a — every site-authored file maps to an entry.
+  for (const p of authored) {
+    if (entries.some((e) => e.patterns.some((re) => re.test(p)))) continue;
+    out.push({
+      file: join(ROOT, p),
+      line: 1,
+      rule: `site-authored source file with no ${MANIFEST_PATH} entry`,
+      reason:
+        "Fix: add an entry to customizations.yaml whose paths match it, with its request issue and its build-in decision (build-in: ailk#N | build-in: site — <decider>, <date>, <reason> | undecided while undecided_ok_until is in the future). AILK builds a customization in unless it decides not to.",
+    });
+  }
+
+  // R5c — a build-in AILK will carry takes its tests with it.
+  for (const e of entries) {
+    const n = DECISION_AILK.exec(e.decision)?.[1];
+    if (!n) continue;
+    const tests = authored.filter((p) => isTestFile(p) && e.patterns.some((re) => re.test(p)));
+    if (tests.length === 0) continue;
+    out.push({
+      file: manifest,
+      line: e.line,
+      rule: `customization "${e.id}" is build-in: ailk#${n} but its paths still match test files in this site: ${tests.join(", ")}`,
+      reason: `tests belong in AILK — move them into ailk#${n}'s PR and delete the site copies when the bump lands.`,
+    });
+  }
+  return out;
+}
+
+// ── Shadow copies (#9201) ────────────────────────────────────────────────
+//
+// #9191 refuses a fork by name; a module copied out of node_modules into an
+// app carries none. A site-authored file most of whose substantive lines are
+// a shipped module's is a copy, edited or not. A wrapper that imports and
+// re-exports or composes the module shares almost none of them. The shipped
+// modules are the code files under the roots the installed packages' export
+// maps (`exports`, `main`, `module`) point at, read from the site root's,
+// each workspace's and pnpm's hoisted (`node_modules/.pnpm/node_modules`)
+// `node_modules`, and indexed once per run — and not at all while no
+// site-authored file reaches the size floor (a fresh scaffold). Two paths:
+// an edited copy of a module of 12+ lines at 60% overlap, and a verbatim or
+// near-verbatim copy of one of 5+ lines at 90% — nearly half the shipped
+// modules are under 12 lines, and no wrapper reproduces a small module's
+// lines verbatim. The shipped form is compiled JS; a copy of a package's
+// TypeScript source compiles to different lines and is outside this check.
+
+/** An edited copy: both sides have at least this many substantive lines ... */
+const SHADOW_MIN_LINES = 12;
+/** ... and this share of the shorter side's lines is found in the other. */
+const SHADOW_MIN_OVERLAP = 0.6;
+/** A verbatim copy: both sides have at least this many substantive lines ... */
+const SHADOW_VERBATIM_MIN_LINES = 5;
+/** ... and this share of the shorter side's lines is found in the other. */
+const SHADOW_VERBATIM_OVERLAP = 0.9;
+/**
+ * Either way, this share of the FILE's own lines is the module's: a file most
+ * of whose lines are its own merely contains a helper the module also has.
+ */
+const SHADOW_MIN_OWN_SHARE = 0.3;
+/** A line in more shipped modules than this is boilerplate and carries no evidence. */
+const SHADOW_COMMON_LINE = 20;
+/** A longer line is a minified bundle's, never a line of a copy; it is not indexed. */
+const SHADOW_MAX_LINE_CHARS = 2000;
+const NOT_A_MODULE_RE = /\.(?:d\.[cm]?ts|map)$|\.(?:test|spec|stories)\.[cm]?[jt]sx?$/;
+/** A whole-line comment: `//`, a block-comment opener, a ` * ` body line or its closer. */
+const COMMENT_LINE_RE = /^\s*(?:\/\/|\/\*|\*)/;
+/** A shipped root is walked whole — `dist` is not skipped here. */
+const SHIPPED_SKIP_DIRS = new Set(["node_modules", "__tests__"]);
+
+/**
+ * A module's substantive lines: whole-line comments (never a `/*` inside a
+ * string or glob literal — an inline comment stays part of its line, on both
+ * sides alike), directives and import/export-from lines (the specifiers a copy
+ * rewrites) dropped, all whitespace removed, quotes unified, and anything
+ * under ten characters left out (`}`, `);`, `return(`). Order is kept;
+ * callers take the set.
+ */
+function substantiveLines(content: string): string[] {
+  const out: string[] = [];
+  for (const raw of content.split("\n")) {
+    if (raw.length > SHADOW_MAX_LINE_CHARS || COMMENT_LINE_RE.test(raw)) continue;
+    const line = raw.replace(/\s+/g, "").replace(/'/g, '"');
+    if (line.length < 10) continue;
+    if (/^(?:import|export)(?:[^"]*from)?"/.test(line) || /^"use[a-z]+"/.test(line)) continue;
+    out.push(line);
+  }
+  return out;
+}
+
+/** Every code-file target in an export-map value (a string, an array or a conditions object). */
+function exportTargets(value: unknown, out: string[] = []): string[] {
+  if (typeof value === "string") {
+    if (CODE_FILE_RE.test(value) && !NOT_A_MODULE_RE.test(value)) out.push(value);
+  } else if (Array.isArray(value)) {
+    for (const v of value) exportTargets(v, out);
+  } else if (value && typeof value === "object") {
+    for (const v of Object.values(value)) exportTargets(v, out);
+  }
+  return out;
+}
+
+/** A package's export map with its subpath keys at the top: a bare conditions object is the root's. */
+function exportsBySubpath(exports: unknown): Record<string, unknown> {
+  if (!exports || typeof exports !== "object" || Array.isArray(exports)) return { ".": exports };
+  const map = exports as Record<string, unknown>;
+  return Object.keys(map).some((k) => k.startsWith(".")) ? map : { ".": map };
+}
+
+/** The installed in-scope packages' shipped modules, each labelled `<package>/<subpath>`, sorted by label. */
+function shippedModules(scope: string): { label: string; file: string }[] {
+  const out: { label: string; file: string }[] = [];
+  const seen = new Set<string>();
+  // A package's realpath is compared against the real root: a temp or home dir may sit behind a symlink.
+  const realRoot = realpathSync(ROOT);
+  const own = workspacesOnDisk();
+  const slash = scope.indexOf("/");
+  const [scopeDir, prefix] = slash === -1 ? ["", scope] : [scope.slice(0, slash), scope.slice(slash + 1)];
+  const dirs = ["", ...own].map((ws) => join(ROOT, ws, "node_modules", scopeDir));
+  dirs.push(join(ROOT, "node_modules", ".pnpm", "node_modules", scopeDir)); // pnpm's hoisted transitive packages
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    for (const entry of readdirSync(dir).sort()) {
+      if (!entry.startsWith(prefix) || !existsSync(join(dir, entry, "package.json"))) continue;
+      let pkg: PackageJson;
+      let pkgDir: string;
+      try {
+        pkgDir = realpathSync(join(dir, entry));
+        pkg = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8")) as PackageJson;
+      } catch {
+        warnings.push(`architecture: warning — shadow-copy check skipped ${rel(join(dir, entry))}: unreadable package.json`);
+        continue;
+      }
+      const name = typeof pkg.name === "string" ? pkg.name : `${scopeDir}/${entry}`;
+      const key = `${name}@${String(pkg.version)}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      // pnpm may hoist the site's own workspace (`@working-theory/mcp` is apps/mcp); its dist is the site's build.
+      const ownPath = toPosix(relative(realRoot, pkgDir));
+      if (own.includes(ownPath)) {
+        if (VERBOSE) {
+          warnings.push(
+            `architecture: warning — shadow-copy check skipped ${name}: ${ownPath} is this site's own workspace, not an installed package`,
+          );
+        }
+        continue;
+      }
+
+      // Each export key's code targets are named by the key; every other file
+      // under the shipped roots is named by its path inside the package.
+      const labels = new Map<string, string>();
+      const targets = exportTargets([pkg.main, pkg.module]);
+      for (const [subpath, value] of Object.entries(exportsBySubpath(pkg.exports))) {
+        const files = exportTargets(value);
+        targets.push(...files);
+        if (!subpath.startsWith(".") || subpath.includes("*")) continue;
+        for (const f of files) {
+          const file = resolve(pkgDir, f);
+          if (!labels.has(file)) labels.set(file, subpath === "." ? name : `${name}/${subpath.slice(2)}`);
+        }
+      }
+      const roots = [...new Set(targets.map((t) => dirname(resolve(pkgDir, t))))]
+        .filter((r) => r.startsWith(pkgDir) && existsSync(r))
+        .filter((r, _, all) => !all.some((o) => o !== r && r.startsWith(`${o}/`)));
+      const files = roots.flatMap((r) => walk(r, CODE_FILE_RE, [], SHIPPED_SKIP_DIRS));
+      for (const file of files.filter((f) => !NOT_A_MODULE_RE.test(f))) {
+        out.push({ file, label: labels.get(file) ?? `${name}/${toPosix(relative(pkgDir, file))}` });
+      }
+    }
+  }
+  // Sorted so a tie between two modules with the same lines reports the same label on every machine.
+  return out.sort((a, b) => a.label.localeCompare(b.label) || a.file.localeCompare(b.file));
+}
+
+/** A file's distinct substantive lines, or null when it cannot be read (a dangling symlink). */
+function lineSet(file: string): Set<string> | null {
+  try {
+    return new Set(substantiveLines(readFileSync(file, "utf8")));
+  } catch {
+    return null;
+  }
+}
+
+function checkShadowCopies(cfg: ArchConfig): Violation[] {
+  const record = cfg.customizations ? readRecord() : null;
+  if (record === null) return []; // without the site-authored set there is nothing to compare
+  const scope = cfg.upgradeable_consumer?.package_scope ?? "@working-theory/";
+  // Walked again rather than threaded out of checkCustomizations: apps/ is small.
+  const candidates = siteAuthoredFiles(record, cfg.customizations?.scaffold_paths ?? [])
+    .map((p) => ({ path: p, lines: lineSet(join(ROOT, p)) }))
+    .filter((c): c is { path: string; lines: Set<string> } => (c.lines?.size ?? 0) >= SHADOW_VERBATIM_MIN_LINES);
+  if (candidates.length === 0) return [];
+
+  const modules = shippedModules(scope);
+  const index = new Map<string, number[]>();
+  const sizes = modules.map(() => 0);
+  modules.forEach((m, id) => {
+    for (const line of lineSet(m.file) ?? []) {
+      const ids = index.get(line);
+      if (ids) ids.push(id);
+      else index.set(line, [id]);
+    }
+  });
+  const common = new Set<string>();
+  for (const [line, ids] of index) {
+    if (ids.length > SHADOW_COMMON_LINE) {
+      common.add(line);
+      index.delete(line);
+    } else {
+      for (const id of ids) sizes[id] = sizes[id]! + 1;
+    }
+  }
+
+  const out: Violation[] = [];
+  for (const c of candidates) {
+    const own = [...c.lines].filter((line) => !common.has(line));
+    if (own.length < SHADOW_VERBATIM_MIN_LINES) continue;
+    const shared = new Map<number, number>();
+    for (const line of own) {
+      for (const id of index.get(line) ?? []) shared.set(id, (shared.get(id) ?? 0) + 1);
+    }
+    let best: { id: number; overlap: number } | undefined;
+    for (const [id, n] of shared) {
+      const shorter = Math.min(own.length, sizes[id]!);
+      if (shorter < SHADOW_VERBATIM_MIN_LINES || n < own.length * SHADOW_MIN_OWN_SHARE) continue;
+      const overlap = n / shorter;
+      if (overlap < (shorter < SHADOW_MIN_LINES ? SHADOW_VERBATIM_OVERLAP : SHADOW_MIN_OVERLAP)) continue;
+      if (!best || overlap > best.overlap) best = { id, overlap };
+    }
+    if (!best) continue;
+    out.push({
+      file: join(ROOT, c.path),
+      line: 1,
+      rule: `shadow copy of ${modules[best.id]!.label} — ${Math.round(best.overlap * 100)}% of the shorter side's substantive lines are shared`,
+      reason:
+        "Fix: delete the copy and import, compose or configure the published module instead — a copy stops taking upstream fixes.",
+    });
+  }
+  return out;
+}
+
+/** `--seed-customizations`: print the entries an existing site needs; write nothing. */
+function seedCustomizations(cfg: ArchConfig): void {
+  if (!cfg.customizations) {
+    console.error("architecture: architecture.yaml declares no customizations: block — run create-ailk --sync-architecture <modules> first");
+    process.exitCode = 1;
+    return;
+  }
+  const record = readRecord();
+  if (record === null) {
+    console.error(`architecture: cannot seed without ${RECORD_PATH} — run create-ailk update first`);
+    process.exitCode = 1;
+    return;
+  }
+  const entries = readManifest([])?.entries ?? [];
+  const unmatched = siteAuthoredFiles(record, cfg.customizations.scaffold_paths ?? []).filter(
+    (p) => !entries.some((e) => e.patterns.some((re) => re.test(p))),
+  );
+  const byDir = new Map<string, string[]>();
+  for (const p of unmatched) {
+    const dir = p.slice(0, p.lastIndexOf("/"));
+    byDir.set(dir, [...(byDir.get(dir) ?? []), p]);
+  }
+  const ids = new Set(entries.map((e) => e.id));
+  const lines: string[] = [];
+  for (const dir of [...byDir.keys()].sort()) {
+    const base = dir.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    let id = base;
+    for (let n = 2; ids.has(id); n++) id = `${base}-${n}`;
+    ids.add(id);
+    lines.push(`  - id: ${JSON.stringify(id)}`, "    paths:");
+    for (const p of byDir.get(dir)!) lines.push(`      - ${JSON.stringify(p)}`);
+    lines.push('    decision: "undecided"');
+  }
+  if (lines.length > 0) process.stdout.write(`${lines.join("\n")}\n`);
+}
+
 function main(): void {
   const yamlPath = join(ROOT, "architecture.yaml");
   if (!existsSync(yamlPath)) {
@@ -274,6 +1016,10 @@ function main(): void {
     return;
   }
   const cfg = (parseYaml(readFileSync(yamlPath, "utf8")) ?? {}) as ArchConfig;
+  if (process.argv.includes("--seed-customizations")) {
+    seedCustomizations(cfg);
+    return;
+  }
   const workspaces = workspacesOnDisk();
   const names = packageNames(workspaces);
   const violations: Violation[] = [];
@@ -297,7 +1043,11 @@ function main(): void {
     }
   }
   violations.push(...checkNamespaces(cfg));
+  violations.push(...checkUpgradeableConsumer(cfg));
+  violations.push(...checkCustomizations(cfg));
+  violations.push(...checkShadowCopies(cfg));
 
+  for (const w of warnings) console.error(w);
   if (violations.length === 0) {
     console.log("architecture: OK");
     return;