@decocms/start 2.22.0 → 2.24.0

package/MIGRATION_TOOLING_PLAN.md

@@ -239,6 +239,58 @@ Each item carries a status: ⬜ pending, 🟡 in progress, ✅ done, 🚫 blocke
 
 > Append-only. Each entry: date, what we found, where it impacts the plan.
 
+### 2026-05-01 — Wave 15-A double-check exposed a self-perpetuating template→audit loop
+
+- **Q1 (sites→packages promotion completeness):** Two subagents
+  swept `casaevideo-storefront` + `baggagio-tanstack`. The big
+  A-list icebergs are caught — but **5 cross-site duplications
+  satisfying D4** slipped through (`useSuggestions`, `useOffer`
+  forks, `useVariantPossibilities` forks, site-local copies of
+  framework `clx` / `useSendEvent`, three competing `Picture`
+  APIs). Plus 4 migration debts where the framework already has
+  the answer (`useCart` factory not adopted in casaevideo,
+  `runtime.ts` inline proxy still scaffolded, location matcher
+  duplication, inline cookie helpers).
+- **Q2 (script/skill coverage of what we shipped):** Worse. The
+  migration script's templates were **scaffolding code that the
+  audit's `--fix` then removed** — the textbook
+  self-perpetuating loop. `templates/vite-config.ts` was emitting
+  `site-manual-chunks` + `deco-stub-meta-gen` (both already
+  inside `decoVitePlugin()`). `templates/server-entry.ts` was
+  emitting a 47-line `createNestedInvokeProxy` body (already in
+  `@decocms/start/sdk`). The factories shipped in W12 (`createUseUser`
+  / `createUseWishlist`) had **zero skill mentions** — the
+  pre-W12 manual approach was still the canonical doc. Cookie
+  passthrough helpers in `cookiePassthrough.ts` were **half-shipped**:
+  the deco-start side compiled, the apps-start providers it
+  references in its own docstring don't exist, and the migration
+  script never wired either.
+- **Decided: ship Wave 15-A as a single PR.** Drop the obsolete
+  emissions (G1/G2/G4/G5), expand `dead-runtime-shim` to catch
+  both the legacy inline shape (with `Runtime` export) and the
+  Wave-15-A canonical re-export shape (skip — desired form),
+  publish a `platform-hooks-factories.md` skill that supersedes
+  the stale README, and update plan + journal.
+- **Defer to Wave 15-B / 16:** (G3) promotion of the
+  `invoke.gen.ts` 170-LOC server-fn block to apps-start needs
+  research on TanStack Start's compiler scanning behaviour
+  (whether `createServerFn` can be transformed when it lives in
+  a node_module). (H1) full cookie-passthrough provider wiring
+  (`setRequestCookieProvider` / `setResponseCookieForwarder` in
+  apps-start, auto-wire in `setup.ts`) needs design. The 5
+  cross-site convergence promotions (`useSuggestions`,
+  `useOffer` factory, `Picture` unification, `clx`/`useSendEvent`
+  redirects, `relative()` extension) are now in the priority-2
+  backlog, sequenced after Wave 15-A merges.
+- **The double-check itself is a useful primitive.** "Did we
+  ship script/skill/audit coverage for everything we built?" run
+  against the framework + apps inventory consistently surfaces
+  these loops. Codify it: when promoting a new factory or
+  helper, the PR checklist must include "matching template
+  emit", "matching audit-rule expansion", "matching skill doc
+  entry". This is the kind of self-check that prevents the next
+  16-month-old stale skill.
+
 ### 2026-05-01 — Wave 14-A rescoped from three codemods to one based on real als data
 
 - **Pre-data plan vs post-data plan.** The plan called for three
@@ -984,6 +1036,189 @@ recipes in `references/htmx-rewrite.md`.
   not the import), but the import-removal would create dead
   references. Order is correct.
 
+### Wave 15-A (close template→audit loops + factories skill — Priority 2 follow-on) — 🟡 **IN FLIGHT**
+
+Triggered by the double-check audit on 2026-05-01: subagent sweeps over
+casaevideo-storefront + baggagio-tanstack revealed (a) the migration
+template was scaffolding code that the audit's `--fix` then removed,
+and (b) the W12 factory hooks (`createUseUser`, `createUseWishlist`)
+had no skill coverage. Wave 15-A closes both loops in one PR.
+
+**Shipped (one PR against `decocms/deco-start`):**
+
+37. `feat(migrate): close template→audit loops for vite plugins, runtime, cookies, branding + factories skill` 🟡 **WAITING ON CI**.
+    - **`templates/vite-config.ts`** — drop `site-manual-chunks` and
+      `deco-stub-meta-gen` plugin emissions. Both already live in
+      `decoVitePlugin()` (`src/vite/plugin.js`). The audit's
+      `obsolete-vite-plugins --fix` was undoing the template's own
+      output; now the template emits clean, the audit catches
+      regressions in legacy sites.
+    - **`templates/server-entry.ts` `generateRuntime()`** — replace
+      the 47-line inline `createNestedInvokeProxy` body with a 6-line
+      re-export from `@decocms/start/sdk`. Sites keep
+      `import { invoke } from "~/runtime"` and `Runtime.invoke`
+      shapes. A2 of the original investigation finally lands at the
+      template layer (was previously only patched post-migration by
+      the audit).
+    - **`templates/server-entry.ts` `generateInvoke()` (VTEX path)**
+      — replace inline `mergeSetCookies` helper with
+      `forwardResponseCookies` from
+      `@decocms/start/sdk/cookiePassthrough`. The framework helper
+      already shipped with try/catch for build-time safety.
+      `getVtexCookies` stays inline (it's auth-specific filtering, not
+      generic passthrough — see Wave 15-B/16 for full provider wiring
+      under H1).
+    - **`templates/routes.ts` + `templates/commerce-loaders.ts`** —
+      replace casaevideo-specific branding leaks ("Tudo para sua
+      casa…" tagline, "O melhor site de compras online…"
+      `productListPageCollection` SEO description) with
+      `${siteTitle}`-derived defaults plus `MIGRATION TODO` markers
+      pointing at the per-site customization spot. CMS `Site.seo`
+      overrides the defaults at runtime so leaving them visible in
+      pre-resolution states is the safe behaviour.
+    - **Audit rule expansion: `dead-runtime-shim`** — previously only
+      flagged when exports were exactly `{ invoke }` or
+      `{ invoke, createNestedInvokeProxy }`. Updated to detect (a)
+      inline `createNestedInvokeProxy` body via regex (catches the
+      legacy 47-line shape **with** `Runtime` export — which the old
+      heuristic missed entirely; this is the shape every existing
+      VTEX site has) and (b) skip the new Wave-15-A canonical
+      re-export shape (where `import invoke from
+      @decocms/start/sdk` is present and no inline proxy body
+      exists). Auto-fix is gated by `safeToAutoFix` metadata: legacy
+      shim shapes get the rewrite + delete; sites that mix the proxy
+      with custom helpers get a warning only. Three new tests.
+      **Verified against casaevideo-storefront**: now flags
+      `[invoke, Runtime] inline createNestedInvokeProxy body` (was
+      missed entirely before).
+    - **Skill: `references/platform-hooks-factories.md`** — new
+      canonical doc covering `createUseCart` / `createUseUser` /
+      `createUseWishlist`. Replaces the pre-W12 manual approach of
+      hand-rolling 200+ LOC of `createServerFn` wrappers per site.
+      Documents the 5-line shim shape, why factories instead of
+      direct hook imports (state isolation per site), non-VTEX
+      stubs using `@decocms/start/sdk/signal`, and the migration
+      path off the manual approach.
+    - **Skill update: `references/platform-hooks/README.md`** —
+      retained as legacy reference but now opens with a
+      "deprecated, see canonical" header pointing at the new doc.
+      The pre-W12 `createServerFn` examples are kept for sites that
+      haven't migrated to factories yet.
+    - **`SKILL.md` index update** — Phase 5 entry now points to the
+      factories doc; reference table lists both new + legacy paths.
+    - 342 → 345 tests pass, typecheck clean, smoke against casaevideo
+      + baggagio confirms expanded rule fires correctly on legacy
+      shapes and stays silent on baggagio (no `runtime.ts` file there).
+
+**Deferred to Wave 15-B / 16 (intentionally — see discoveries journal):**
+
+- **G3** — promote the 170-LOC `invoke.gen.ts` VTEX `createServerFn`
+  wrappers into `@decocms/apps/vtex/server-fns`. Needs research on
+  whether TanStack Start's compiler can transform `createServerFn`
+  call sites that live inside a node_module. Not safe to ship blind.
+- **H1** — full cookie-passthrough provider wiring
+  (`setRequestCookieProvider` / `setResponseCookieForwarder` in
+  apps-start, auto-wire in `templates/setup.ts`). The
+  `cookiePassthrough.ts` docstring already references this design but
+  the apps-start side doesn't exist. Needs a design pass to scope
+  what calls inside `vtex/utils/fetch.ts` need the provider hook
+  (currently each call site forwards cookies manually).
+- **Cross-site convergence promotions** (5 items) — `useSuggestions`,
+  `useOffer` factory, `Picture` API unification, redirect
+  `useSendEvent`/`clx`/location-matcher imports, `relative()`
+  SKU-stripping extension. Sequenced after 15-A merges.
+
+### Wave 15-B-1 (cross-site convergence — `local-framework-duplicate` audit rule) — 🟡 **IN FLIGHT**
+
+First slice of the cross-site-convergence backlog deferred from
+Wave 15-A. Concrete data first (per the user-rule "verify before
+designing"): the `useSendEvent`/`clx`/location-matcher promotion
+turned out to be *not* a "promote site code → framework" exercise.
+The framework already has each helper. The work is **enforcing the
+existing canonical** when sites carry their own copy.
+
+Verified state (2026-05-01 grep against both sites):
+
+| Item | casaevideo | baggagio | Action |
+|---|---|---|---|
+| `src/sdk/clx.ts` | absent (already canonical) | present, identical body + dead `clsx` alias (zero callers) | pure dup → **auto-fix** |
+| `src/sdk/useSendEvent.ts` | absent | present, **stricter** typing (`<E extends AnalyticsEvent>` generic) vs framework's permissive shape | **warn-only** (replacing 1:1 weakens types) |
+| `src/matchers/location.ts` | present, cookie-only subset of framework | absent | **warn-only** (framework's `registerBuiltinMatchers()` is a behavior superset; needs per-site verification of country-name lookup parity) |
+
+So this is exactly *one* mechanically-applicable fix (`clx` in
+baggagio) plus two judgement calls. Hand-applying would be cheap;
+the value is making the audit *enforce* the convergence so the next
+copy-paste regression on any future site gets caught automatically.
+
+**Shipped (one PR against `decocms/deco-start`):**
+
+38. `feat(migrate): local-framework-duplicate audit rule with registry-driven enforcement` 🟡 **WAITING ON CI**
+    - **New rule `local-framework-duplicate`** in
+      `scripts/migrate/post-cleanup/rules.ts` driven by an exported
+      `FRAMEWORK_DUPLICATES` registry. Each entry is `{ id,
+      sitePath, canonicalImport, contentSignature: RegExp[],
+      safeToAutoFix, reason?, description }`. The rule fires only
+      when **every** content-signature regex matches the site file
+      — conservative on purpose so genuinely-forked helpers are
+      skipped.
+    - **Auto-fix path** (when `safeToAutoFix: true`): rewrite all
+      `from "~/<derived>"` importers to `from
+      "<canonicalImport>"` via the existing `rewriteImportSpec`
+      helper, then delete the file. Already-canonical importers
+      are left untouched.
+    - **Warn-only path** (when `safeToAutoFix: false`): rule still
+      fires + populates the finding's `fix:` field with the
+      `reason` so engineers see *why* auto-fix is gated and what
+      they need to verify before manual cleanup.
+    - **Three initial entries** in the registry, mapped 1:1 to the
+      cross-site audit findings:
+      | id | site path | canonical | auto-fix? |
+      |---|---|---|---|
+      | `clx` | `src/sdk/clx.ts` | `@decocms/start/sdk/clx` | **yes** |
+      | `use-send-event` | `src/sdk/useSendEvent.ts` | `@decocms/start/sdk/analytics` | no (typing regression) |
+      | `location-matcher` | `src/matchers/location.ts` | `@decocms/start/matchers/builtins` | no (behavior superset, parity check needed) |
+    - **11 new tests** covering: pure-dup detection, fork detection
+      (signature mismatch → no flag), warn-only entries, severity
+      uniformity (warning for both kinds, so `--strict` gates
+      everything), auto-fix happy-path (delete + rewrite both
+      importers, leave canonical importers alone), warn-only
+      auto-fix is a no-op (does NOT delete partial-overlap files),
+      mixed coexistence (auto-fixable `clx` and warn-only
+      `useSendEvent` in the same tree → only `clx` gets auto-fixed),
+      `supportsAutoFix` flag is true (since rule has `applyFix`).
+    - **CLI help text + `post-migration-cleanup.md` § 8** updated
+      with the new rule's table and the "adding a new entry"
+      section. Old § 8 (orphan TODO comments) renumbered to § 9.
+    - 345 → 353 tests pass, typecheck clean, end-to-end disk smoke
+      against a temp fixture confirmed: 2 importers rewritten + 1
+      file deleted in one `--fix` run.
+    - **Real-site smoke**:
+      - **baggagio**: rule fires twice — `clx.ts` (auto-fixable),
+        `useSendEvent.ts` (warn-only with the typed-generic reason).
+      - **casaevideo**: rule fires once — `location.ts` (warn-only
+        with the `registerBuiltinMatchers()` adoption hint).
+    - **Net**: every future site that copy-pastes any of these three
+      files gets a tight audit finding + auto-fix on the safe one.
+      The registry pattern means adding a 4th cross-site duplicate
+      is a single object literal — no new rule, no new tests
+      scaffolding, no new doc section.
+
+**Still in the cross-site backlog (sequenced behind 15-B-1):**
+
+- **15-B-2** — `useSuggestions` framework helper (new export in
+  `@decocms/start/sdk` typed by `Resolved<T>`, optional Sentry
+  hook). Sites adopt incrementally; once 2+ adopt, add a registry
+  entry pointing the legacy hand-rolled implementations at the
+  canonical via `local-framework-duplicate`.
+- **15-B-3** — `useOffer` factory (D4 candidate; needs design pass
+  for PIX/installment plugin slots).
+- **15-B-4** — `Picture` API unification (breaking; needs a
+  picking-the-winner pass between casaevideo's and baggagio's
+  shapes, plus a codemod for call sites).
+- **15-B-5** — `relative()` SKU-stripping option in
+  `@decocms/apps/commerce/sdk/url`. Apps-side change; sites delete
+  their wrapper.
+
 ### Wave 15+ (htmx cleanup PRs on als + propagation to other sites) — Priority 3 / 4
 
 Each htmx pattern that survives the codemod becomes a per-pattern PR

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.22.0",
+  "version": "2.24.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/migrate/post-cleanup/rules.ts

@@ -462,6 +462,31 @@ function findAttachedLeadingComments(content: string, openIdx: number): number {
 /* Rule 3 — dead `src/runtime.ts` invoke shim                          */
 /* ------------------------------------------------------------------ */
 
+/**
+ * Detection covers two shapes of `src/runtime.ts`:
+ *
+ * 1. Legacy inline proxy (pre-Wave 15-A migration template) — defines
+ *    `createNestedInvokeProxy` plus `invoke` and `Runtime` constants.
+ *    The whole 40-50 LOC body duplicates `@decocms/start/sdk`'s `invoke`.
+ *
+ * 2. Simple re-export shim — the file only re-exports `invoke` /
+ *    `createNestedInvokeProxy` (no inline proxy body, but also not yet
+ *    pointing at `@decocms/start/sdk`).
+ *
+ * Both should be replaced with `import { invoke } from "@decocms/start/sdk"`
+ * at every callsite, and the file deleted. The Wave 15-A migration template
+ * scaffolds a thin re-export form that's also acceptable (re-exports
+ * `invoke` from `@decocms/start/sdk` and rebuilds `Runtime = { invoke }`);
+ * we explicitly skip it via the "imports invoke from @decocms/start/sdk
+ * AND no inline proxy" check below.
+ */
+const INLINE_PROXY_RE =
+  /(?:function|const)\s+createNestedInvokeProxy\b|new\s+Proxy\s*\(\s*Object\.assign\s*\(\s*async\s*\(\s*props/;
+const FRAMEWORK_INVOKE_IMPORT_RE =
+  /import\s+\{[^}]*\binvoke\b[^}]*\}\s+from\s+['"]@decocms\/start(?:\/sdk)?['"]/;
+
+const ALLOWED_RUNTIME_EXPORTS = new Set(["invoke", "createNestedInvokeProxy", "Runtime"]);
+
 const ruleDeadRuntimeShim: Rule = {
   id: "dead-runtime-shim",
   title: "Dead src/runtime.ts invoke shim",
@@ -469,24 +494,54 @@ const ruleDeadRuntimeShim: Rule = {
     const abs = `${siteDir}/src/runtime.ts`;
     if (!fs.exists(abs)) return [];
     const content = fs.readText(abs);
-    // Heuristic: if the file's only meaningful exports are `invoke` /
-    // `createNestedInvokeProxy`, it's purely a shim.
+
+    const hasInlineProxy = INLINE_PROXY_RE.test(content);
+    const reExportsFromFramework = FRAMEWORK_INVOKE_IMPORT_RE.test(content);
     const exports = extractExports(content);
-    const onlyInvokeShim =
-      exports.length > 0 && exports.every((e) => ["invoke", "createNestedInvokeProxy"].includes(e));
-    if (!onlyInvokeShim) return [];
+    const onlyKnownInvokeExports =
+      exports.length > 0 && exports.every((e) => ALLOWED_RUNTIME_EXPORTS.has(e));
+
+    // Wave 15-A canonical template: re-exports invoke from @decocms/start/sdk
+    // and exposes `Runtime = { invoke }` for legacy callers. No inline proxy
+    // body. This is the desired shape — skip.
+    if (reExportsFromFramework && !hasInlineProxy) return [];
+
+    // Site-specific helpers alongside invoke: don't flag — the file has its
+    // own purpose beyond shimming. (Old behavior preserved.)
+    if (!hasInlineProxy && !onlyKnownInvokeExports) return [];
+
+    const exportSummary = exports.length > 0 ? exports.join(", ") : "(re-exports only)";
+    const flavor = hasInlineProxy ? "inline createNestedInvokeProxy body" : "shim re-exports";
+    // Only safe to auto-delete when exports are pure invoke surface; if a
+    // legacy file mixes the inline proxy with custom helpers, we still flag
+    // it but skip the destructive fix.
+    const safeToAutoFix = onlyKnownInvokeExports;
+
     return [
       {
         rule: "dead-runtime-shim",
         severity: "info",
         file: "src/runtime.ts",
-        message: `Only re-exports invoke (${exports.join(", ")}) — replace with @decocms/start/sdk`,
-        fix: 'rg -l "from \\"~/runtime\\"" src/ | xargs sed -i \'\' \'s|from "~/runtime"|from "@decocms/start/sdk"|g\' && rm src/runtime.ts',
+        message: safeToAutoFix
+          ? `${flavor} [${exportSummary}] — replace with @decocms/start/sdk`
+          : `${flavor} [${exportSummary}] — manual review: file mixes the runtime proxy with site-specific exports`,
+        fix: safeToAutoFix
+          ? 'rg -l "from \\"~/runtime\\"" src/ | xargs sed -i \'\' \'s|from "~/runtime"|from "@decocms/start/sdk"|g\' && rm src/runtime.ts'
+          : "Move the inline `createNestedInvokeProxy` body to call @decocms/start/sdk's `invoke`; relocate site-specific helpers to a dedicated module before deleting src/runtime.ts",
+        meta: {
+          hasInlineProxy,
+          exports,
+          safeToAutoFix,
+        },
       },
     ];
   },
   applyFix(ctx, findings, writer): FixAction[] {
     if (findings.length === 0) return [];
+    // Honor the per-finding safety gate emitted by run() — never auto-delete
+    // a runtime.ts that mixes the proxy with site-specific helpers.
+    const safe = findings.every((f) => f.meta?.safeToAutoFix !== false);
+    if (!safe) return [];
     const updated = rewriteImportSpec(ctx, writer, "~/runtime", "@decocms/start/sdk");
     writer.deleteFile(`${ctx.siteDir}/src/runtime.ts`);
     return [
@@ -888,6 +943,181 @@ const ruleFrameworkTodos: Rule = {
   },
 };
 
+/* ------------------------------------------------------------------ */
+/* Rule — `local-framework-duplicate` — site-local copy of fwk code   */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Registry of files we expect sites to NOT carry locally because the
+ * canonical implementation already lives in `@decocms/start` (or a
+ * sibling apps package).
+ *
+ * Two flavours:
+ *  - `safeToAutoFix: true`  — site file is a behaviour-equivalent dup
+ *    of the framework export. `--fix` rewrites every `from "~/<path>"`
+ *    importer to `from "<canonicalImport>"` and deletes the file.
+ *  - `safeToAutoFix: false` — site file *overlaps* with framework code
+ *    but isn't a clean drop-in (different typing, partial coverage,
+ *    stricter behaviour, etc.). The rule still flags it so the entry
+ *    surfaces in audits, but never deletes — the `reason` explains why
+ *    a human has to make the call.
+ *
+ * `contentSignature` regexes ALL must match the site file's contents
+ * before the rule fires. They are deliberately specific enough to
+ * avoid catching forks that happen to share a filename but have
+ * diverged.
+ */
+interface FrameworkDuplicate {
+  /** Stable id surfaced in finding meta and CLI/JSON output. */
+  id: string;
+  /** Site-relative path of the duplicated file (e.g. "src/sdk/clx.ts"). */
+  sitePath: string;
+  /** Canonical import to rewrite to. */
+  canonicalImport: string;
+  /**
+   * Heuristic content fingerprint. The site file must match every
+   * regex for the rule to consider it the framework dup.
+   */
+  contentSignature: RegExp[];
+  /**
+   * When true, the rule's `applyFix` will rewrite all importers and
+   * delete the file. When false, the rule emits a warning only —
+   * `reason` explains the manual judgement required.
+   */
+  safeToAutoFix: boolean;
+  /**
+   * Required when `safeToAutoFix: false`. Surfaces in the finding's
+   * `fix:` field so users see *why* the auto-fix is gated.
+   */
+  reason?: string;
+  /**
+   * Human-readable one-liner shown in the finding message and used
+   * to compose the `fix:` hint when auto-fixable.
+   */
+  description: string;
+}
+
+/**
+ * Add an entry here when:
+ *  - 1+ migrated sites carry their own copy of code that already
+ *    exists in `@decocms/start` (or a sibling apps package), AND
+ *  - the canonical version is at least feature-equivalent.
+ *
+ * Per D4 in the migration tooling policy, the framework promotion
+ * itself happens at 3+ sites — but once promoted, this registry is
+ * how we *enforce* convergence on the remaining sites.
+ */
+export const FRAMEWORK_DUPLICATES: FrameworkDuplicate[] = [
+  {
+    id: "clx",
+    sitePath: "src/sdk/clx.ts",
+    canonicalImport: "@decocms/start/sdk/clx",
+    contentSignature: [
+      /export\s+const\s+clx\s*=/,
+      /args\.filter\(Boolean\)\.join/,
+    ],
+    safeToAutoFix: true,
+    description: "src/sdk/clx.ts duplicates @decocms/start/sdk/clx",
+  },
+  {
+    id: "use-send-event",
+    sitePath: "src/sdk/useSendEvent.ts",
+    canonicalImport: "@decocms/start/sdk/analytics",
+    contentSignature: [
+      /export\s+(?:const|function)\s+useSendEvent/,
+      /data-event/,
+      /encodeURIComponent/,
+    ],
+    safeToAutoFix: false,
+    reason:
+      "site copy uses a typed AnalyticsEvent generic; the framework export is permissive. " +
+      "Replacing 1:1 weakens type-safety. Either widen the framework export (preferred), or " +
+      "rewrite call sites to drop the generic. Manual review required.",
+    description:
+      "src/sdk/useSendEvent.ts overlaps with @decocms/start/sdk/analytics → useSendEvent",
+  },
+  {
+    id: "location-matcher",
+    sitePath: "src/matchers/location.ts",
+    canonicalImport: "@decocms/start/matchers/builtins",
+    contentSignature: [
+      /registerMatcher\(\s*['"]website\/matchers\/location\.ts['"]/,
+      /__cf_geo/,
+    ],
+    safeToAutoFix: false,
+    reason:
+      "framework's registerBuiltinMatchers() ships a richer location matcher (request.cf + " +
+      "geo cookies + headers + 10 sibling matchers). Adopting it changes behaviour: " +
+      "verify country-name lookup parity (resolveCountryCode vs site's inline table) and " +
+      "swap setup.ts's customMatchers entry to call registerBuiltinMatchers().",
+    description:
+      "src/matchers/location.ts overlaps with @decocms/start/matchers/builtins → registerBuiltinMatchers()",
+  },
+];
+
+const ruleLocalFrameworkDuplicate: Rule = {
+  id: "local-framework-duplicate",
+  title: "Site-local copy of framework code",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const findings: Finding[] = [];
+    for (const dup of FRAMEWORK_DUPLICATES) {
+      const abs = `${siteDir}/${dup.sitePath}`;
+      if (!fs.exists(abs)) continue;
+      const content = fs.readText(abs);
+      const matchesAll = dup.contentSignature.every((re) => re.test(content));
+      if (!matchesAll) continue;
+
+      const fixMessage = dup.safeToAutoFix
+        ? `Auto-fixable: rewrite \`from "~/${stripExt(dup.sitePath.replace(/^src\//, ""))}"\` → \`from "${dup.canonicalImport}"\` and delete ${dup.sitePath}.`
+        : dup.reason ?? "Manual review required.";
+
+      findings.push({
+        rule: "local-framework-duplicate",
+        severity: "warning",
+        file: dup.sitePath,
+        message: `${dup.description}${dup.safeToAutoFix ? " (pure dup)" : " (partial overlap)"}`,
+        fix: fixMessage,
+        meta: {
+          id: dup.id,
+          canonicalImport: dup.canonicalImport,
+          safeToAutoFix: dup.safeToAutoFix,
+          ...(dup.reason ? { reason: dup.reason } : {}),
+        },
+      });
+    }
+    return findings;
+  },
+  applyFix(ctx, findings, writer): FixAction[] {
+    const actions: FixAction[] = [];
+    for (const f of findings) {
+      const id = f.meta?.id as string | undefined;
+      const safe = f.meta?.safeToAutoFix === true;
+      if (!safe || !id) continue;
+      const dup = FRAMEWORK_DUPLICATES.find((d) => d.id === id);
+      if (!dup) continue;
+
+      const siteImportSpec = `~/${stripExt(dup.sitePath.replace(/^src\//, ""))}`;
+      const updated = rewriteImportSpec(
+        ctx,
+        writer,
+        siteImportSpec,
+        dup.canonicalImport,
+      );
+      writer.deleteFile(`${ctx.siteDir}/${dup.sitePath}`);
+      actions.push({
+        file: dup.sitePath,
+        kind: "rewrite-imports+delete",
+        detail: `rewrote ${updated.length} import(s) "${siteImportSpec}" → "${dup.canonicalImport}" and deleted ${dup.sitePath}`,
+      });
+    }
+    return actions;
+  },
+};
+
+function stripExt(path: string): string {
+  return path.replace(/\.(ts|tsx|js|jsx|mjs)$/, "");
+}
+
 /* ------------------------------------------------------------------ */
 /* Rule 8 — `htmx-residue` — leftover hx-* attrs in migrated src/      */
 /* ------------------------------------------------------------------ */
@@ -966,6 +1196,7 @@ export const ALL_RULES: Rule[] = [
   ruleVtexShimRegression,
   ruleLocalWidgetsTypes,
   ruleFrameworkTodos,
+  ruleLocalFrameworkDuplicate,
   ruleHtmxResidue,
 ];
 
@@ -982,5 +1213,6 @@ export const _internals = {
     ruleHtmxResidue,
     ruleLocalWidgetsTypes,
     ruleFrameworkTodos,
+    ruleLocalFrameworkDuplicate,
   },
 };