create-ailk 0.20.0 → 0.22.0

package/dist/sync-routes.d.ts

@@ -1,4 +1,6 @@
 import type { WorkspaceVersionMap } from "./substitute.js";
+/** The site test that fails a route neither rendered through `renderPage` nor in its `NO_STRUCTURED_DATA_ROUTES` (#8704). */
+export declare const STRUCTURED_DATA_TEST_PATH = "apps/web/lib/__tests__/structured-data.test.tsx";
 export interface SyncRoutesOptions {
     /**
      * The already-scaffolded repo (absolute or relative). Must exist, be a
@@ -65,7 +67,32 @@ export interface SyncRoutesResult {
     missingMessageNamespaces: string[];
     /** Gateable surface ids the target does not carry, sorted. */
     skippedSurfaces: string[];
+    /**
+     * When `apply` added a route the template exempts in its structured-data
+     * test and the site's copy of that test is site-edited (its bytes differ
+     * from the recorded hash), each template `NO_STRUCTURED_DATA_ROUTES` entry
+     * the site's test lacks, verbatim, with the added routes it covers (#8704).
+     * Sorted by entry; empty otherwise. The site's test is never written.
+     */
+    structuredDataEntries: Array<{
+        routes: string[];
+        entry: string;
+    }>;
+}
+/** One `NO_STRUCTURED_DATA_ROUTES` element: its source text, dedented, and the routes it exempts. */
+interface StructuredDataExemption {
+    route: string;
+    subtree: boolean;
+    text: string;
 }
+/**
+ * The elements of `source`'s `NO_STRUCTURED_DATA_ROUTES` array literal, by a
+ * brace scan that skips string literals and comments. Empty when the
+ * file declares no such array. It assumes what the template's array holds:
+ * object literals of string, boolean and identifier-array values — no regex
+ * literal or `${…}` interpolation.
+ */
+export declare function parseStructuredDataExemptions(source: string): StructuredDataExemption[];
 /**
  * The template's route directories, ROUTE_ROOT-relative and sorted.
  *
@@ -99,3 +126,4 @@ export declare const SYNC_ROUTES_HELP = "create-ailk sync-routes \u2014 copy tem
  * like `parseCliArgs`; at most one positional.
  */
 export declare function parseSyncRoutesArgs(argv: string[]): SyncRoutesArgs;
+export {};

package/dist/sync-routes.js

@@ -21,7 +21,10 @@
  *     route root is copied once into a scratch dir and compared from there.
  *   - Never overwrite, never delete. A route dir the site has changed is
  *     reported as modified and left alone; `--apply` only creates directories
- *     that do not exist, so a second run is a no-op.
+ *     that do not exist, so a second run is a no-op. When the site has edited
+ *     its structured-data test, a route `--apply` adds that the template
+ *     exempts there is reported with the exact `NO_STRUCTURED_DATA_ROUTES`
+ *     entry to add — the test itself is never written (#8704).
  *
  * Pure module: no `import.meta.url`, so jest can import it directly. The
  * package's own `templates/` dir is supplied by programmatic.ts.
@@ -35,9 +38,12 @@ import { appendEnvRows } from "./lib/declared-env.js";
 import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { substituteMarkers } from "./substitute.js";
 import { GATEABLE_SURFACES, NON_ROUTE_DIRS, ROUTE_DEPENDENCIES, ROUTE_MESSAGE_NAMESPACES, ROUTE_SINCE, surfaceForRouteDir, } from "./surfaces.js";
+import { TEMPLATE_RECORD_PATH, parseTemplateRecord, sha256Hex } from "./template-record.js";
 import { SPOKE_SEAM_FILES, isSpokeExcluded, readSpokeShape, } from "./topology.js";
 /** Template-relative prefix every `apps/web` route directory sits under. */
 const ROUTE_ROOT = "apps/web/app/[locale]";
+/** The site test that fails a route neither rendered through `renderPage` nor in its `NO_STRUCTURED_DATA_ROUTES` (#8704). */
+export const STRUCTURED_DATA_TEST_PATH = "apps/web/lib/__tests__/structured-data.test.tsx";
 /**
  * `<surface id>/<entry name>` pairs that live directly under a GATEABLE
  * surface's top-level directory but belong to a DIFFERENT module (#5366).
@@ -50,6 +56,115 @@ const ROUTE_ROOT = "apps/web/app/[locale]";
 const NESTED_FOREIGN_MODULE_ENTRIES = new Set([
     "projects/apply",
 ]);
+/**
+ * The elements of `source`'s `NO_STRUCTURED_DATA_ROUTES` array literal, by a
+ * brace scan that skips string literals and comments. Empty when the
+ * file declares no such array. It assumes what the template's array holds:
+ * object literals of string, boolean and identifier-array values — no regex
+ * literal or `${…}` interpolation.
+ */
+export function parseStructuredDataExemptions(source) {
+    const decl = source.indexOf("const NO_STRUCTURED_DATA_ROUTES");
+    if (decl === -1)
+        return [];
+    const open = /=\s*\[/.exec(source.slice(decl));
+    if (open === null)
+        return [];
+    const out = [];
+    let depth = 0;
+    let start = -1;
+    for (let i = decl + open.index + open[0].length; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === '"' || ch === "'" || ch === "`") {
+            for (i++; i < source.length && source[i] !== ch; i++) {
+                if (source[i] === "\\")
+                    i++;
+            }
+            continue;
+        }
+        if (ch === "/" && source[i + 1] === "/") {
+            const eol = source.indexOf("\n", i);
+            i = eol === -1 ? source.length : eol;
+            continue;
+        }
+        if (ch === "/" && source[i + 1] === "*") {
+            const end = source.indexOf("*/", i + 2);
+            i = end === -1 ? source.length : end + 1;
+            continue;
+        }
+        if (ch === "{") {
+            if (depth === 0)
+                start = i;
+            depth++;
+        }
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0 && start !== -1) {
+                const raw = source.slice(start, i + 1) + (source[i + 1] === "," ? "," : "");
+                const route = /\broute:\s*["']([^"']+)["']/.exec(raw)?.[1];
+                if (route !== undefined) {
+                    const indent = /[ \t]*$/.exec(source.slice(source.lastIndexOf("\n", start) + 1, start))?.[0] ?? "";
+                    const text = raw
+                        .split("\n")
+                        .map((line) => (line.startsWith(indent) ? line.slice(indent.length) : line))
+                        .join("\n");
+                    out.push({ route, subtree: /\bsubtree:\s*true\b/.test(raw), text });
+                }
+                start = -1;
+            }
+        }
+        else if (ch === "]" && depth === 0) {
+            break;
+        }
+    }
+    return out;
+}
+/**
+ * The first exemption covering `route` by the structured-data test's route
+ * rule (`route` itself, or under a `subtree` entry). An entry's `requires`
+ * strings are not checked: they key only the standard spoke checkout pages
+ * (#8748), which `surfaceForRouteDir` leaves unclassified, so no `--apply`
+ * ever adds them.
+ */
+function exemptionFor(exemptions, route) {
+    return exemptions.find((e) => route === e.route || (e.subtree && route.startsWith(`${e.route}/`)));
+}
+/**
+ * The template `NO_STRUCTURED_DATA_ROUTES` entries the site's structured-data
+ * test must gain for `added` routes (#8704). Empty unless that test is
+ * recorded and site-edited — an untouched copy is `create-ailk update`'s to
+ * bring forward, and an unrecorded one cannot be told apart from an edit.
+ */
+function structuredDataEntriesFor(targetAbs, templatesDir, added) {
+    const sitePath = join(targetAbs, STRUCTURED_DATA_TEST_PATH);
+    const templatePath = join(templatesDir, STRUCTURED_DATA_TEST_PATH);
+    const recordPath = join(targetAbs, TEMPLATE_RECORD_PATH);
+    if (added.length === 0 || !existsSync(sitePath) || !existsSync(templatePath) || !existsSync(recordPath)) {
+        return [];
+    }
+    let recordedHash;
+    try {
+        recordedHash = parseTemplateRecord(readFileSync(recordPath, "utf8")).files[STRUCTURED_DATA_TEST_PATH]?.sha256;
+    }
+    catch {
+        return [];
+    }
+    const siteBytes = readFileSync(sitePath);
+    if (recordedHash === undefined || sha256Hex(siteBytes) === recordedHash)
+        return [];
+    const templateExemptions = parseStructuredDataExemptions(readFileSync(templatePath, "utf8"));
+    const siteExemptions = parseStructuredDataExemptions(siteBytes.toString("utf8"));
+    const byEntry = new Map();
+    for (const route of [...added].sort()) {
+        const needed = exemptionFor(templateExemptions, route);
+        if (needed === undefined || exemptionFor(siteExemptions, route) !== undefined)
+            continue;
+        byEntry.set(needed.text, [...(byEntry.get(needed.text) ?? []), route]);
+    }
+    return [...byEntry.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([entry, routes]) => ({ routes, entry }));
+}
 /**
  * The template's route directories, ROUTE_ROOT-relative and sorted.
  *
@@ -276,6 +391,7 @@ export function syncRoutes(opts) {
         appliedDependencies,
         missingMessageNamespaces,
         skippedSurfaces,
+        structuredDataEntries: structuredDataEntriesFor(targetAbs, opts.templatesDir, applied),
     };
 }
 /**
@@ -355,6 +471,13 @@ export function formatSyncRoutesReport(result, apply) {
         lines.push(`[create-ailk] Also required — message namespace(s) not found in apps/web/messages/en.json (add manually, not auto-merged):`);
         lines.push(...result.missingMessageNamespaces.map((ns) => `  ${ns}`));
     }
+    if (result.structuredDataEntries.length > 0) {
+        lines.push(`[create-ailk] Also required — ${STRUCTURED_DATA_TEST_PATH} is edited here, so add these NO_STRUCTURED_DATA_ROUTES entries to it by hand (not written):`);
+        for (const { routes, entry } of result.structuredDataEntries) {
+            lines.push(`  for ${routes.join(", ")}:`);
+            lines.push(...entry.split("\n").map((line) => `    ${line}`));
+        }
+    }
     if (result.missing.length > 0 && !apply) {
         lines.push("Run `create-ailk sync-routes <target> --apply` to copy the missing routes.");
     }

package/dist/template-record.d.ts

@@ -3,9 +3,10 @@ export declare const TEMPLATE_RECORD_PATH = ".ailk-template-files.json";
 /**
  * The app paths a generator rewrites after `copyTemplate` lands its copy
  * (§1): the nav, the site chrome, the site fonts, the paid-sections
- * registry, and the four spoke seams. Composed from each writer's own
- * exported path constant, so a renamed constant carries its path along
- * here too (#8522 D2).
+ * registry, the four spoke seams, and a commerce spoke's checkout config,
+ * which the checkout writer stamps and the site owns from then on (#8748
+ * D2). Composed from each writer's own exported path constant, so a renamed
+ * constant carries its path along here too (#8522 D2).
  */
 export declare const REGENERATED_APP_PATHS: readonly string[];
 /**

package/dist/template-record.js

@@ -21,6 +21,7 @@ import { join } from "node:path";
 import { PAID_SECTIONS_PATH } from "./paid-sections.js";
 import { SITE_CHROME_PATH } from "./site-chrome.js";
 import { SITE_FONTS_PATH } from "./site-fonts.js";
+import { SPOKE_CHECKOUT_CONFIG_PATH } from "./spoke-checkout.js";
 import { NAV_CONFIG_PATH } from "./surfaces.js";
 import { SPOKE_SEAM_FILES } from "./topology.js";
 /** Where the per-file record lives, beside `.ailk-site-manifest.json`. */
@@ -28,9 +29,10 @@ export const TEMPLATE_RECORD_PATH = ".ailk-template-files.json";
 /**
  * The app paths a generator rewrites after `copyTemplate` lands its copy
  * (§1): the nav, the site chrome, the site fonts, the paid-sections
- * registry, and the four spoke seams. Composed from each writer's own
- * exported path constant, so a renamed constant carries its path along
- * here too (#8522 D2).
+ * registry, the four spoke seams, and a commerce spoke's checkout config,
+ * which the checkout writer stamps and the site owns from then on (#8748
+ * D2). Composed from each writer's own exported path constant, so a renamed
+ * constant carries its path along here too (#8522 D2).
  */
 export const REGENERATED_APP_PATHS = [
     NAV_CONFIG_PATH,
@@ -38,6 +40,7 @@ export const REGENERATED_APP_PATHS = [
     SITE_FONTS_PATH,
     PAID_SECTIONS_PATH,
     ...SPOKE_SEAM_FILES,
+    SPOKE_CHECKOUT_CONFIG_PATH,
 ];
 const REGENERATED_SET = new Set(REGENERATED_APP_PATHS);
 const RECORDABLE_APP_ROOT = /^apps\/(web|api|mcp)\//;

package/dist/topology.js

@@ -174,6 +174,29 @@ export function isRemovableClosureMember(path, opts = {}) {
     return (p.split("/").includes("__tests__") ||
         prefixes.some((prefix) => underPrefix(p, prefix)));
 }
+/**
+ * The relative module specifiers a file reaches that are NOT static imports:
+ * a jest module reference (`jest.mock("../auth")`, `doMock`, `unmock`,
+ * `setMock`, `requireActual`, `requireMock`, `createMockFromModule`) or a
+ * `require(...)`. A suite that mocks a seed by path ships a dangling
+ * reference on a spoke exactly as one that imports it would (#8758), yet the
+ * shared import walk (`relativeImportsOf`) sees only `import`/`export ... from`
+ * and `import()` — it is shared with the module-slice lints, so the extra
+ * forms are read here rather than widening it for them.
+ */
+function referencedModulesOf(absPath) {
+    const specs = relativeImportsOf(absPath);
+    let src;
+    try {
+        src = readFileSync(absPath, "utf8");
+    }
+    catch {
+        return specs;
+    }
+    for (const m of src.matchAll(/\b(?:jest\s*\.\s*(?:mock|doMock|unmock|setMock|requireActual|requireMock|createMockFromModule)|require)\s*\(\s*["'`](\.[^"'`]*)["'`]/g))
+        specs.push(m[1]);
+    return specs;
+}
 /**
  * Every path a spoke does not carry, computed over the built `templates/`
  * tree: the removed roots, the seeds that apply, and every source file under
@@ -209,7 +232,7 @@ export function spokeExclusions(templatesDir, opts) {
         for (const file of candidates) {
             if (closed.has(file))
                 continue;
-            for (const spec of relativeImportsOf(join(templatesDir, file))) {
+            for (const spec of referencedModulesOf(join(templatesDir, file))) {
                 const target = resolveRelativeImport(file, spec, candidates);
                 if (target !== undefined && closed.has(target)) {
                     closed.add(file);
@@ -899,6 +922,7 @@ export function renderSpokeHardFloors(opts) {
         "    reason: Stripe webhook route — payment state requires human review",
         "  - paths:",
         '      - "apps/web/app/api/checkout/**"',
+        '      - "apps/web/lib/checkout.ts"',
         '      - "apps/web/lib/checkout-config.ts"',
         '      - ".github/workflows/checkout-e2e.yml"',
         "    reason: Spoke checkout — the buy route, the price map and the checkout e2e workflow require human review",

package/dist/update.d.ts

@@ -31,6 +31,11 @@ export interface UpdateResult {
         path: string;
         reason: string;
     }>;
+    /** Per file left under review or skipped, the template tests importing it that stay at the site's version (#8704). */
+    heldBack: Array<{
+        file: string;
+        tests: string[];
+    }>;
     backfilled?: {
         version: string;
         files: number;
@@ -43,6 +48,6 @@ export interface UpdateArgs {
     target: string | undefined;
     help: boolean;
 }
-export declare const UPDATE_HELP = "create-ailk update \u2014 bring template fixes into a site's copied app code.\n\nUsage:\n  create-ailk update [<target-dir>]\n\nArguments:\n  <target-dir>             The existing site. Defaults to the current dir.\n\nOptions:\n  --help, -h               Print this message.\n\nReads .ailk-template-files.json (written beside .ailk-site-manifest.json by\nevery template scaffold) to tell an untouched copy from an edit. An\nuntouched apps/web, apps/api or apps/mcp file whose template copy changed is\noverwritten. An edited file whose template copy also changed is three-way\nmerged with `git` (git must be on PATH); a conflict leaves the file alone\nand is listed under \"Needs review\" \u2014 nothing else in the run is held back.\nA site with no record gets one on its first run, from the version its\n.ailk-site-manifest.json already records. Commit before running, and review\nthe diff after.\n";
+export declare const UPDATE_HELP = "create-ailk update \u2014 bring template fixes into a site's copied app code.\n\nUsage:\n  create-ailk update [<target-dir>]\n\nArguments:\n  <target-dir>             The existing site. Defaults to the current dir.\n\nOptions:\n  --help, -h               Print this message.\n\nReads .ailk-template-files.json (written beside .ailk-site-manifest.json by\nevery template scaffold) to tell an untouched copy from an edit. An\nuntouched apps/web, apps/api or apps/mcp file whose template copy changed is\noverwritten. An edited file whose template copy also changed is three-way\nmerged with `git` (git must be on PATH); a conflict leaves the file alone\nand is listed under \"Needs review\". Every template test that imports a file\nleft under \"Needs review\" or \"Skipped\" (by a relative import) is held at the\nsite's version with it, its record entry is not advanced, and it is listed\nunder \"Held back with <file>\" \u2014 reconcile the file, then run update again to\nbring its tests forward. Every other file in the run still updates.\nA site with no record gets one on its first run, from the version its\n.ailk-site-manifest.json already records. Commit before running, and review\nthe diff after.\n";
 /** Parse the argv AFTER the `update` word. Strict `node:util` parseArgs, like `parseAdoptArgs`. */
 export declare function parseUpdateArgs(argv: string[]): UpdateArgs;

package/dist/update.js

@@ -9,10 +9,12 @@
  * version's copy — read from this package's own `templates/` when that is
  * the running version, else re-materialised from the published npm tarball
  * (`lib/fetch-template-snapshot.ts`) — and the running version's copy. A
- * conflict leaves the file untouched and is listed under "Needs review". A
- * site with no record gets one backfilled from `.ailk-site-manifest.json`'s
- * `patternVersion` on its first run, then updates normally. Every refusal
- * throws before the first write.
+ * conflict leaves the file untouched and is listed under "Needs review". Every
+ * template test that imports a file left under review or skipped is held at
+ * the site's version with it, so a run never leaves a test newer than the
+ * code it exercises (#8704). A site with no record gets one backfilled from
+ * `.ailk-site-manifest.json`'s `patternVersion` on its first run, then
+ * updates normally. Every refusal throws before the first write.
  *
  * Pure module: no `import.meta.url` — the CLI supplies `templatesDir`, the
  * `adopt.ts` / `add-route.ts` split.
@@ -26,6 +28,7 @@ import { fetchTemplateSnapshot } from "./lib/fetch-template-snapshot.js";
 import { mergeThreeWay } from "./lib/merge-three-way.js";
 import { ParseError } from "./parse-args.js";
 import { SITE_ROSTER_PATH } from "./site-roster.js";
+import { SPOKE_CHECKOUT_TEMPLATE_PATHS } from "./spoke-checkout.js";
 import { excludedRoutePaths } from "./surfaces.js";
 import { TEMPLATE_RECORD_PATH, isRecordable, parseTemplateRecord, serializeTemplateRecord, sha256Hex, } from "./template-record.js";
 import { TopologyError, isSpokeExcluded, readSpokeShape, spokeExclusions, } from "./topology.js";
@@ -132,6 +135,50 @@ function containsKnownPath(prefix, knownPaths) {
     }
     return false;
 }
+/** A template test file: a `*.test.*` / `*.spec.*` module, or anything under `__tests__/`. */
+const TEST_FILE = /(^|\/)__tests__\/|\.(test|spec)\.[cm]?[jt]sx?$/;
+/** Module specifiers `import`/`export … from`, `import()`, `require()` and `jest.mock()` name. */
+const IMPORT_SPECIFIER = /\bfrom\s*["']([^"']+)["']|\bimport\s*["']([^"']+)["']|\b(?:import|require|jest\.mock|jest\.requireActual)\s*\(\s*["']([^"']+)["']/g;
+const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"];
+/**
+ * The record-style paths a relative specifier in `fromPath` can resolve to:
+ * the path as written, with each source extension, a `.js`-family suffix
+ * swapped for its TypeScript source, and as a directory's `index.*`.
+ */
+function relativeImportCandidates(fromPath, specifier) {
+    const parts = fromPath.split("/").slice(0, -1);
+    for (const segment of specifier.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..")
+            parts.pop();
+        else
+            parts.push(segment);
+    }
+    const target = parts.join("/");
+    const out = [target, ...RESOLVE_EXTENSIONS.map((ext) => `${target}${ext}`)];
+    const jsSuffix = /\.([cm]?)jsx?$/.exec(target);
+    if (jsSuffix !== null) {
+        const stem = target.slice(0, -jsSuffix[0].length);
+        out.push(`${stem}.${jsSuffix[1]}ts`, `${stem}.tsx`);
+    }
+    out.push(...RESOLVE_EXTENSIONS.map((ext) => `${target}/index${ext}`));
+    return out;
+}
+/** The files of `held` that `text`, the source of `fromPath`, imports by relative specifier. */
+function importedHeldFiles(fromPath, text, held) {
+    const out = new Set();
+    for (const match of text.matchAll(IMPORT_SPECIFIER)) {
+        const specifier = match[1] ?? match[2] ?? match[3];
+        if (specifier === undefined || !specifier.startsWith("."))
+            continue;
+        for (const candidate of relativeImportCandidates(fromPath, specifier)) {
+            if (held.has(candidate))
+                out.add(candidate);
+        }
+    }
+    return [...out];
+}
 export async function updateSite(opts) {
     const targetDir = resolve(opts.targetDir);
     const version = opts.version;
@@ -202,9 +249,13 @@ export async function updateSite(opts) {
     }
     const excludedRoutes = excludedRoutePaths(header.surfaces);
     const spokeExclusionList = spoke !== undefined ? spokeExclusions(opts.templatesDir, spoke) : undefined;
+    // #8748 D3 — the standard spoke checkout is a commerce spoke's alone.
+    const sellsAsSpoke = spoke !== undefined && header.modules.includes("commerce");
     const outOfScope = (destRel) => {
         if (isExcluded(destRel, excludedRoutes))
             return true;
+        if (!sellsAsSpoke && isExcluded(destRel, SPOKE_CHECKOUT_TEMPLATE_PATHS))
+            return true;
         if (spoke !== undefined && spokeExclusionList !== undefined) {
             return isSpokeExcluded(destRel, { ...spoke, exclusions: spokeExclusionList });
         }
@@ -391,37 +442,85 @@ export async function updateSite(opts) {
         nextFiles[path] = { sha256: sha256Hex(newBytes), version };
         added.push(path);
     }
+    // ── Hold back the template tests of every file left alone (#8704) ────
+    // A test this run would move forward (update, merge, add, remove, or
+    // advance as current) that imports a file under review or skipped stays
+    // exactly as the site has it, and its row keeps its recorded version — so
+    // the tests on disk always match the code they exercise. The imports are
+    // read from both the site's copy and the running template's: either one
+    // exercising the held file is enough. A held test-support file
+    // (`__tests__/fixtures.ts`) holds the tests importing it in turn, until no
+    // further test is held.
+    const heldFiles = new Set([...review, ...skipped].map((row) => row.path));
+    const heldBackByFile = new Map();
+    const heldTests = new Set();
+    const moving = [...updated, ...merged, ...added, ...removed, ...current]
+        .filter((path) => TEST_FILE.test(path))
+        .sort();
+    for (let grew = heldFiles.size > 0; grew;) {
+        grew = false;
+        for (const path of moving) {
+            if (heldTests.has(path))
+                continue;
+            const sources = [];
+            const abs = join(targetDir, ...path.split("/"));
+            if (existsSync(abs))
+                sources.push(readFileSync(abs, "utf8"));
+            const newBytes = newMap.get(path);
+            if (newBytes !== undefined)
+                sources.push(Buffer.from(newBytes).toString("utf8"));
+            const imported = new Set(sources.flatMap((text) => importedHeldFiles(path, text, heldFiles)));
+            if (imported.size === 0)
+                continue;
+            heldTests.add(path);
+            heldFiles.add(path);
+            grew = true;
+            for (const file of imported) {
+                heldBackByFile.set(file, [...(heldBackByFile.get(file) ?? []), path]);
+            }
+        }
+    }
+    for (const path of heldTests) {
+        const recorded = record.files[path];
+        if (recorded !== undefined)
+            nextFiles[path] = recorded;
+        else
+            delete nextFiles[path];
+    }
+    const notHeld = (path) => !heldTests.has(path);
+    const heldBack = [...heldBackByFile.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([file, tests]) => ({ file, tests }));
     // ── Apply: writes and removals, then the record (D4 Order) ───────────
-    for (const write of writes) {
+    for (const write of writes.filter((w) => notHeld(w.path))) {
         const abs = join(targetDir, ...write.path.split("/"));
         mkdirSync(dirname(abs), { recursive: true });
         writeFileSync(abs, write.bytes);
     }
-    for (const path of deletes) {
+    for (const path of deletes.filter(notHeld)) {
         rmSync(join(targetDir, ...path.split("/")));
     }
     const backfilled = backfillPatternVersion !== undefined
         ? { version: backfillPatternVersion, files: Object.keys(record.files).length }
         : undefined;
-    const recordChanged = backfilled !== undefined ||
-        updated.length > 0 ||
-        merged.length > 0 ||
-        added.length > 0 ||
-        removed.length > 0 ||
-        current.length > 0;
+    const moved = {
+        updated: updated.filter(notHeld),
+        merged: merged.filter(notHeld),
+        added: added.filter(notHeld),
+        removed: removed.filter(notHeld),
+        current: current.filter(notHeld),
+    };
+    const recordChanged = backfilled !== undefined || Object.values(moved).some((paths) => paths.length > 0);
     if (recordChanged) {
         writeFileSync(recordPath, serializeTemplateRecord({ schema: 1, projectName: record.projectName, files: nextFiles }));
     }
     return {
         targetDir,
         version,
-        updated,
-        merged,
-        added,
-        removed,
-        current,
+        ...moved,
         review,
         skipped,
+        heldBack,
         ...(backfilled !== undefined ? { backfilled } : {}),
     };
 }
@@ -448,6 +547,10 @@ export function formatUpdateReport(result) {
         lines.push(`Needs review (${result.review.length}):`);
         lines.push(...result.review.map((row) => `  ${row.path} — ${row.reason}`));
     }
+    for (const { file, tests } of result.heldBack) {
+        lines.push(`Held back with ${file} (${tests.length}):`);
+        lines.push(...tests.map((path) => `  ${path}`));
+    }
     if (result.skipped.length > 0) {
         lines.push(`Skipped (${result.skipped.length}):`);
         lines.push(...result.skipped.map((row) => `  ${row.path} — ${row.reason}`));
@@ -481,7 +584,11 @@ every template scaffold) to tell an untouched copy from an edit. An
 untouched apps/web, apps/api or apps/mcp file whose template copy changed is
 overwritten. An edited file whose template copy also changed is three-way
 merged with \`git\` (git must be on PATH); a conflict leaves the file alone
-and is listed under "Needs review" — nothing else in the run is held back.
+and is listed under "Needs review". Every template test that imports a file
+left under "Needs review" or "Skipped" (by a relative import) is held at the
+site's version with it, its record entry is not advanced, and it is listed
+under "Held back with <file>" — reconcile the file, then run update again to
+bring its tests forward. Every other file in the run still updates.
 A site with no record gets one on its first run, from the version its
 .ailk-site-manifest.json already records. Commit before running, and review
 the diff after.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,8 +28,8 @@
     "tar": "^7.5.21"
   },
   "devDependencies": {
-    "@working-theory/schema": "0.41.0",
-    "@working-theory/templates": "0.41.0"
+    "@working-theory/schema": "0.43.0",
+    "@working-theory/templates": "0.43.0"
   },
   "repository": {
     "type": "git",

package/site-templates/_base/ailk-template.json

@@ -1,6 +1,6 @@
 {
   "name": "_base",
   "requires": [],
-  "$comment": "The BASE LAYER (#5618 D1) — not a template. Every declared template reaches this tree by `extends: \"_base\"`; scaffold() installs it through installBundleTree before any module bundle and before the template's own tree, only when --template is named. It carries the seed content every template brings itself and no module owns: /pricing, /privacy and /terms (spec 5462 D16). No installMap: every file here is unmapped and lands at its own path under the scaffold root's content/, so a template overrides a base page by shipping the same path. Never published as a registry bundle; the leading underscore is the skip signal for the bundle producer and the site-templates/ directory scans.",
-  "postInstall": "Base layer installed: seed copy for /pricing, /privacy and /terms is in content/en/ - replace the placeholder copy before you launch."
+  "$comment": "The BASE LAYER (#5618 D1) — not a template. Every declared template reaches this tree by `extends: \"_base\"`; scaffold() installs it through installBundleTree before any module bundle and before the template's own tree, only when --template is named. It carries the seed content every template brings itself and no module owns: /pricing, /privacy, /terms (spec 5462 D16) and /working-agreement (#8661 D10). No installMap: every file here is unmapped and lands at its own path under the scaffold root's content/, so a template overrides a base page by shipping the same path. Never published as a registry bundle; the leading underscore is the skip signal for the bundle producer and the site-templates/ directory scans.",
+  "postInstall": "Base layer installed: seed copy for /pricing, /privacy, /terms and /working-agreement is in content/en/ - replace the placeholder copy before you launch."
 }

package/site-templates/_base/content/en/WorkingAgreementPage/working-agreement.mdx

@@ -0,0 +1,78 @@
+---
+type: "WorkingAgreementPage"
+slug: "working-agreement"
+title: "Working Agreement"
+description: "Placeholder working agreement for Your Company. Replace every section with how you actually work with a client before you launch."
+sections:
+  [
+    {
+      "id": "working-agreement-document",
+      "type": "document-chassis",
+      "data":
+        {
+          "headline": "Working Agreement",
+          "layout": "article",
+          "updated": "Last updated {Month Day, Year}",
+          "navGroupLabel": "Contents",
+          "sections":
+            [
+              {
+                "id": "placeholder-notice",
+                "heading": "This is placeholder text",
+                "blocks":
+                  [
+                    {
+                      "kind": "paragraph",
+                      "text": "This page is starter content that shipped with your site. It is not a contract, it binds nobody, and it is not legal advice. Replace every section below with how Your Company actually works with a client, and have someone qualified read it before you publish.",
+                    },
+                    {
+                      "kind": "paragraph",
+                      "text": "Until you do, leave this notice in place so nobody mistakes the page for a finished agreement.",
+                    },
+                  ],
+              },
+              {
+                "id": "what-to-write-here",
+                "heading": "What belongs on this page",
+                "blocks":
+                  [
+                    {
+                      "kind": "paragraph",
+                      "text": "A working agreement sets out how an engagement runs day to day. Write each part about the work you actually do, and keep the sentences short enough that a client can follow them.",
+                    },
+                    {
+                      "kind": "list",
+                      "listStyle": "number",
+                      "items":
+                        [
+                          "How you work with a client, from the first conversation to the last delivery.",
+                          "What each side provides, and when.",
+                          "Timelines, and how and how often you communicate.",
+                          "How changes and cancellations are handled.",
+                          "How the agreement ends, and what happens to the work when it does.",
+                        ],
+                    },
+                  ],
+              },
+              {
+                "id": "contact",
+                "heading": "Questions about this agreement",
+                "blocks":
+                  [
+                    {
+                      "kind": "paragraph",
+                      "text": "Replace this with the address you actually monitor — for example hello@example.com — so a client with a question about the agreement has somewhere to send it.",
+                    },
+                    {
+                      "kind": "paragraph",
+                      "text": "Replace this with the date this agreement last changed, and say what happens when it changes again.",
+                    },
+                  ],
+              },
+            ],
+        },
+    },
+  ]
+---
+
+{/* Rendered from frontmatter `sections[]`. Placeholder seed content — this is not a working agreement and not legal advice. Replace every section before you launch. */}