eslint-plugin-kerfjs 4.4.0 → 4.5.0-beta.1

package/README.md

@@ -7,18 +7,19 @@ ESLint rules that enforce kerf's hard rules. Catches AI-shaped bugs at edit time
 
 This plugin sits alongside two other defense layers shipped by [`kerfjs`](https://brianwestphal.github.io/kerf/):
 
-| Layer | Catches | When |
-|---|---|---|
-| `tsc --noEmit` with strict typings | Hard Rules 8 (partial-set), most type errors | Build time |
-| Opt-in dev-warns (`KERF_DEV_WARN_*`) | Hard Rules 4 (rebuilt listeners), 7 (untracked signals), 8 (narrow set) | Runtime |
-| **This plugin** | Hard Rules 2, 5, 6, 10, 12 — AST-shaped antipatterns; plus rename-safety / `raw()`-audit nudges and a project-hygiene check for the bundled AI-assistant configs | **Edit time** |
+| Layer                                | Catches                                                                                                                                                          | When          |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `tsc --noEmit` with strict typings   | Hard Rules 8 (partial-set), most type errors                                                                                                                     | Build time    |
+| Opt-in dev-warns (`KERF_DEV_WARN_*`) | Hard Rules 4 (rebuilt listeners), 7 (untracked signals), 8 (narrow set)                                                                                          | Runtime       |
+| **This plugin**                      | Hard Rules 2, 5, 6, 10, 12 — AST-shaped antipatterns; plus rename-safety / `raw()`-audit nudges and a project-hygiene check for the bundled AI-assistant configs | **Edit time** |
 
-All but one rule are AST-only — no `@typescript-eslint/parser` *service* dependency is required by the plugin (consumers configure their own parser). The exception, `ai-assistant-configs`, reads the filesystem instead of the AST and runs once per lint pass.
+All but one rule are AST-only — no `@typescript-eslint/parser` _service_ dependency is required by the plugin (consumers configure their own parser). The exception, `ai-assistant-configs`, reads the filesystem instead of the AST and runs once per lint pass.
 
 ## Install
 
 ```bash
 npm install --save-dev eslint-plugin-kerfjs
+npm install @kerfjs/ui
 ```
 
 ### Supported ESLint versions
@@ -33,12 +34,12 @@ A version outside the range is not "probably fine" — it is one nobody has run.
 
 ```js
 // eslint.config.js
-import kerfjs from 'eslint-plugin-kerfjs';
-import tsParser from '@typescript-eslint/parser';
+import kerfjs from "eslint-plugin-kerfjs";
+import tsParser from "@typescript-eslint/parser";
 
 export default [
   {
-    files: ['**/*.ts', '**/*.tsx'],
+    files: ["**/*.ts", "**/*.tsx"],
     languageOptions: {
       parser: tsParser,
       parserOptions: { ecmaFeatures: { jsx: true } },
@@ -48,25 +49,58 @@ export default [
 ];
 ```
 
+Applications using the UI catalog can select one of two additive flat configs:
+
+```js
+export default [
+  // parser/files configuration as above
+  kerfjs.configs['recommended-ui'], // preferences and wiring are warnings
+  // or kerfjs.configs['strict-ui']  // all four UI contracts are errors
+];
+```
+
+The UI rules resolve the installed `@kerfjs/ui` v1 selection catalog, v2 composition catalog, and application profile defaults. They then merge `.kerf-ui-profile.json` files from the workspace root toward the linted file. Package authors and monorepos can provide explicit artifacts without duplicating their facts:
+
+```js
+settings: {
+  kerfjs: {
+    ui: {
+      workspaceRoot: import.meta.dirname,
+      catalogPath: './vendor/component-catalog-v2.json',
+      selectionCatalogPath: './vendor/component-catalog.json',
+      profileDefaultsPath: './vendor/application-ui-profile.defaults.json',
+      profileContractPath: './vendor/application-ui-profile-sync.cjs',
+    },
+  },
+}
+```
+
+For deterministic generated configs, the same settings accept parsed `catalog`, `selectionCatalog`, and `profile` objects. File-based precedence is package defaults, then workspace profile, then root-to-leaf directory profiles. The rules load `application-ui-profile-sync.cjs` from the installed `@kerfjs/ui` package by default because ESLint rule creation is synchronous; `profileContractPath` is only needed when artifacts are vendored. Every raw layer is schema- and catalog-reference-validated before merge, so a child cannot hide malformed or stale parent policy. Exceptions use exact `KUI-L*` diagnostic ids and repository-relative file or directory targets.
+
+`KUI-L090` is reserved for catalog/profile loading and configuration failures; it does not collide with the static analyzer's `KUI-L001`–`KUI-L009` findings. The supported-ESLint matrix installs real packed `eslint-plugin-kerfjs` and `@kerfjs/ui` tarballs in a downstream flat-config fixture, ensuring these defaults resolve from the consumer rather than this repository's source tree.
+
 ## Legacy `.eslintrc` configs are not supported
 
-The package is ESM-only. ESLint's `.eslintrc` system loads plugins with `require()`, which cannot load an ESM package, so `extends: ["plugin:kerfjs/legacy-recommended"]` fails with *"couldn't find the config to extend from"* on ESLint 8 **and** on ESLint 9's legacy mode.
+The package is ESM-only. ESLint's `.eslintrc` system loads plugins with `require()`, which cannot load an ESM package, so `extends: ["plugin:kerfjs/legacy-recommended"]` fails with _"couldn't find the config to extend from"_ on ESLint 8 **and** on ESLint 9's legacy mode.
 
 Use flat config (`eslint.config.js`), shown above. The `legacy-recommended` export still exists in the package but is unreachable through any config system — treat it as deprecated.
 
-
 ## Rules
 
-| Rule | Hard Rule | Severity (recommended) |
-|---|---|---|
-| [`no-inline-jsx-event-handlers`](docs/rules/no-inline-jsx-event-handlers.md) | 10 — use `data-action` + `delegate()` | `error` |
-| [`require-data-key-in-each`](docs/rules/require-data-key-in-each.md) | 2 — `data-key` per item | `error` |
-| [`require-delegate-disposer`](docs/rules/require-delegate-disposer.md) | 5 — capture `delegate()` disposers when scope < page | `warn` |
-| [`no-nested-mount`](docs/rules/no-nested-mount.md) | 6 — one `mount()` per root | `error` |
-| [`prefer-module-jsx-augmentation`](docs/rules/prefer-module-jsx-augmentation.md) | 12 — augment `kerfjs/jsx-runtime`, not global | `error` |
-| [`prefer-attr-selector`](docs/rules/prefer-attr-selector.md) | — (rename-safety nudge for `delegate()` selectors) | `warn` |
-| [`no-raw-with-dynamic-arg`](docs/rules/no-raw-with-dynamic-arg.md) | — (XSS audit trail) | `warn` |
-| [`ai-assistant-configs`](docs/rules/ai-assistant-configs.md) | — (project hygiene) | `warn` |
+| Rule                                                                             | Hard Rule                                            | Severity (recommended) |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------- |
+| [`no-inline-jsx-event-handlers`](docs/rules/no-inline-jsx-event-handlers.md)     | 10 — use `data-action` + `delegate()`                | `error`                |
+| [`require-data-key-in-each`](docs/rules/require-data-key-in-each.md)             | 2 — `data-key` per item                              | `error`                |
+| [`require-delegate-disposer`](docs/rules/require-delegate-disposer.md)           | 5 — capture `delegate()` disposers when scope < page | `warn`                 |
+| [`no-nested-mount`](docs/rules/no-nested-mount.md)                               | 6 — one `mount()` per root                           | `error`                |
+| [`prefer-module-jsx-augmentation`](docs/rules/prefer-module-jsx-augmentation.md) | 12 — augment `kerfjs/jsx-runtime`, not global        | `error`                |
+| [`prefer-attr-selector`](docs/rules/prefer-attr-selector.md)                     | — (rename-safety nudge for `delegate()` selectors)   | `warn`                 |
+| [`no-raw-with-dynamic-arg`](docs/rules/no-raw-with-dynamic-arg.md)               | — (XSS audit trail)                                  | `warn`                 |
+| [`ai-assistant-configs`](docs/rules/ai-assistant-configs.md)                     | — (project hygiene)                                  | `warn`                 |
+| [`ui-public-boundaries`](docs/rules/ui-public-boundaries.md)                     | — (cataloged CSS boundaries)                         | `error`                |
+| [`ui-composition`](docs/rules/ui-composition.md)                                 | — (cataloged parents and zones)                      | `error`                |
+| [`ui-preferences`](docs/rules/ui-preferences.md)                                 | — (application component choices)                    | `warn`                 |
+| [`ui-wiring`](docs/rules/ui-wiring.md)                                           | — (required setup and cleanup)                       | `warn`                 |
 
 The "Hard Rule" column refers to the numbered rules in [`docs/ai/usage-guide.md`](../docs/ai/usage-guide.md) on the main kerf repo. `no-raw-with-dynamic-arg` and `ai-assistant-configs` don't map to numbered Hard Rules — the former creates an audit trail for every dynamic `raw()` call site (potential XSS); the latter checks that the bundled AI-assistant configs are installed and current. See [`docs/12-ai-assistant-configs.md`](../docs/12-ai-assistant-configs.md) on the main kerf repo for the AI-configs design.
 
@@ -83,7 +117,7 @@ npm install
 npm test
 ```
 
-The AST rules' test suites use ESLint's `RuleTester` with `@typescript-eslint/parser`. The `ai-assistant-configs` tests are filesystem-driven — they build temp project roots with fixture `node_modules/kerfjs/ai/` bundles and drive the rule's classifier directly, since `RuleTester` doesn't simulate the filesystem.
+The AST rules' test suites use ESLint's `RuleTester` with `@typescript-eslint/parser`. The `ai-assistant-configs` tests are filesystem-driven — they build temp project roots with fixture `node_modules/kerfjs/ai/` bundles, drive the classifier directly, and use the real ESLint API to prove plain lint is read-only while explicit `--fix` performs the external write.
 
 ## License
 

package/docs/rules/ai-assistant-configs.md

@@ -10,15 +10,15 @@ Maps to design doc [`docs/12-ai-assistant-configs.md`](https://github.com/brianw
 
 The rule resolves `kerfjs/ai/manifest.json` from the consumer's installed `kerfjs` (silently no-ops if `kerfjs` isn't a dep). For each bundled file, it picks a trigger heuristic — "is this project using the tool this file is for?" — and only nudges the consumer when the trigger says yes:
 
-| Bundled file | Triggers when | Installed to |
-|---|---|---|
-| `ai/skill.md` (Claude Code) | `.claude/` directory exists at the project root | `.claude/skills/kerf-app/SKILL.md` |
-| `ai/cursorrules` (Cursor) | `.cursorrules` file or `.cursor/` directory exists | `.cursorrules` |
+| Bundled file                | Triggers when                                      | Installed to                       |
+| --------------------------- | -------------------------------------------------- | ---------------------------------- |
+| `ai/skill.md` (Claude Code) | `.claude/` directory exists at the project root    | `.claude/skills/kerf-app/SKILL.md` |
+| `ai/cursorrules` (Cursor)   | `.cursorrules` file or `.cursor/` directory exists | `.cursorrules`                     |
 
 A triggered file is then classified into one of three reported states (a fourth, "up-to-date," is silent):
 
 - **Missing** — the consumer's `dest` doesn't exist.
-- **Stale** — exists, parses cleanly, but its `kerf-skill-version` line is older than the bundle's.
+- **Stale** — exists, parses cleanly, its `kerf-skill-version` line is older than the bundle's, and its canonical-section hash matches that version in the manifest's history.
 - **Forked** — the consumer's file no longer matches the canonical layout: marker is missing, marker appears more than once, `kerf-skill-version` line is missing, or the content above the marker has been edited.
 
 ## ❌ Reported
@@ -46,7 +46,7 @@ For **missing** files, `--fix` copies the bundled canonical (`node_modules/kerfj
 
 For **stale** files, `--fix` replaces only the content **above and including the `KERF-APP-CANONICAL-END` marker**. Everything below the marker — the consumer's append zone — is preserved byte-for-byte. This is the "versioned-section preservation" strategy from the design doc.
 
-The `fix()` callback writes to a file OTHER than the linted source — unusual for an ESLint rule. ESLint only invokes `fix()` under `--fix`, so the side effect is opt-in by definition; plain `eslint` will report the warning without touching disk.
+The `fix()` callback writes to a file OTHER than the linted source — unusual for an ESLint rule. ESLint evaluates fix callbacks during ordinary lint too, so the callback gates this external write on an explicit CLI `--fix` flag. Plain `eslint` reports the warning without touching disk; `eslint --fix` opts into installation or update.
 
 ## ❗ Forked — no auto-fix
 
@@ -55,7 +55,8 @@ If the consumer has edited the file in a way that breaks the canonical/append-zo
 - **No marker present.** The file pre-dates the marker convention, the consumer deleted the marker, or the file is a hand-written variant. Auto-fixing would either clobber legitimate customizations or leave the file in an ambiguous state.
 - **Multiple markers.** A well-formed file has exactly one. Auto-fix would have to guess which boundary is real.
 - **No `kerf-skill-version` line.** The staleness signal is missing; we can't tell what's there.
-- **Content above the marker has been edited.** The contract is "above the marker is kerf's; below is yours." Above-the-marker edits are a deliberate fork.
+- **Content above the marker has been edited.** The contract is "above the marker is kerf's; below is yours." The rule checks stale files against the historical canonical hash for their own version, so an edited old section is preserved as a deliberate fork rather than overwritten.
+- **Canonical history unavailable.** An old version absent from the shipped manifest history cannot be proven untouched, so the rule conservatively refuses to overwrite it.
 
 Resolution: either restore the canonical layout (move customizations below a freshly-inserted marker, delete extras, re-add the version line) or disable the rule for this project — `'kerfjs/ai-assistant-configs': 'off'` in `eslint.config.js`.
 
@@ -77,4 +78,4 @@ Both `claude` and `cursor` default to `true`. Setting either to `false` makes th
 - It does not install the configs at `npm install` time — there are no postinstall scripts. The first lint pass after `npm install kerfjs` surfaces the recommendation.
 - It does not write to disk under plain `eslint` (no `--fix`). The warning is emitted; nothing changes on disk.
 - It does not push Claude Code or Cursor on consumers who haven't signalled they use them — no `.claude/` or `.cursor*` ⇒ silent.
-- It does not validate the *content* of the canonical files in the bundle. That's the kerf maintainer's responsibility (and the `check:ai-bundle-in-sync` gate in the kerf repo).
+- It does not validate the _content_ of the canonical files in the bundle. That's the kerf maintainer's responsibility (and the `check:ai-bundle-in-sync` gate in the kerf repo).

package/docs/rules/no-inline-jsx-event-handlers.md

@@ -40,8 +40,8 @@ delegate(rootEl, 'submit', ACTIONS.submit.selector,  submit);
 String literals still work for ad-hoc fixed selectors:
 
 ```tsx
-<button data-action="save">Save</button>
-delegate(rootEl, 'click', '[data-action="save"]', save);
+<button data-action="save">Save</button>;
+delegate(rootEl, "click", '[data-action="save"]', save);
 ```
 
 ## Why this rule is AST-only

package/docs/rules/no-nested-mount.md

@@ -24,7 +24,12 @@ mount(bodyRoot, () => <Body />);
 
 // Composition via plain functions:
 const Header = () => <h1>{title.value}</h1>;
-const Body = () => <main><Header /><div>{count.value}</div></main>;
+const Body = () => (
+  <main>
+    <Header />
+    <div>{count.value}</div>
+  </main>
+);
 mount(root, () => <Body />);
 ```
 

package/docs/rules/no-raw-with-dynamic-arg.md

@@ -9,21 +9,21 @@ Warn when `raw()` is called with a dynamic argument (any expression that is not
 ## ❌ Incorrect
 
 ```ts
-raw(userInput)                     // variable reference
-raw(fetchedHtml())                 // function call
-raw(`<b>${title}</b>`)             // template literal with expressions
-raw(isAdmin ? adminHtml : guestHtml)  // conditional expression
+raw(userInput); // variable reference
+raw(fetchedHtml()); // function call
+raw(`<b>${title}</b>`); // template literal with expressions
+raw(isAdmin ? adminHtml : guestHtml); // conditional expression
 ```
 
 ## ✅ Correct
 
 ```ts
-raw('<p>Static markup</p>')        // string literal — no warning
-raw(`<p>Static template</p>`)      // expression-free template literal — no warning
+raw("<p>Static markup</p>"); // string literal — no warning
+raw(`<p>Static template</p>`); // expression-free template literal — no warning
 
 // Dynamic but audited — suppress with eslint-disable
 // eslint-disable-next-line kerfjs/no-raw-with-dynamic-arg
-raw(DOMPurify.sanitize(marked(userMarkdown)))
+raw(DOMPurify.sanitize(marked(userMarkdown)));
 ```
 
 ## Why `warn` and not `error`

package/docs/rules/prefer-attr-selector.md

@@ -7,8 +7,8 @@ Prefer `attr('name', 'value').selector` over a literal `[name="value"]` selector
 ## ❌ Discouraged
 
 ```tsx
-<button data-action="toggle">Toggle</button>
-delegate(root, 'click', '[data-action="toggle"]', handler);
+<button data-action="toggle">Toggle</button>;
+delegate(root, "click", '[data-action="toggle"]', handler);
 ```
 
 The JSX attribute and the selector string are two independent literals; renaming the action key in JSX leaves the delegate selector unchanged, and the handler silently stops firing.
@@ -16,14 +16,14 @@ The JSX attribute and the selector string are two independent literals; renaming
 ## ✅ Recommended
 
 ```tsx
-import { attr, delegate, type AttrSpec } from 'kerfjs';
+import { attr, delegate, type AttrSpec } from "kerfjs";
 
 const ACTIONS = {
-  toggle: attr('data-action', 'toggle'),
-} as const satisfies Record<string, AttrSpec<'data-action'>>;
+  toggle: attr("data-action", "toggle"),
+} as const satisfies Record<string, AttrSpec<"data-action">>;
 
-<button {...ACTIONS.toggle.attrs}>Toggle</button>
-delegate(root, 'click', ACTIONS.toggle.selector, handler);
+<button {...ACTIONS.toggle.attrs}>Toggle</button>;
+delegate(root, "click", ACTIONS.toggle.selector, handler);
 ```
 
 Rename `'toggle'` to `'on'` in the `ACTIONS` map and both the rendered attribute and the delegate selector update — no string-grep migration required.

package/docs/rules/prefer-module-jsx-augmentation.md

@@ -10,7 +10,7 @@ Maps to **kerf Hard Rule 11** — kerf's JSX runtime looks up custom-element typ
 declare global {
   namespace JSX {
     interface IntrinsicElements {
-      'my-tag': { foo?: string };
+      "my-tag": { foo?: string };
     }
   }
 }
@@ -19,10 +19,10 @@ declare global {
 ## ✅ Correct
 
 ```ts
-declare module 'kerfjs/jsx-runtime' {
+declare module "kerfjs/jsx-runtime" {
   namespace JSX {
     interface IntrinsicElements {
-      'my-tag': KerfCustomElement & { foo?: string };
+      "my-tag": KerfCustomElement & { foo?: string };
     }
   }
 }
@@ -31,7 +31,11 @@ declare module 'kerfjs/jsx-runtime' {
 Import the building-block types from `kerfjs/jsx-runtime`:
 
 ```ts
-import type { KerfCustomElement, KerfBaseAttrs, AttrLike } from 'kerfjs/jsx-runtime';
+import type {
+  KerfCustomElement,
+  KerfBaseAttrs,
+  AttrLike,
+} from "kerfjs/jsx-runtime";
 ```
 
 ## What this rule does NOT catch

package/docs/rules/require-data-key-in-each.md

@@ -7,24 +7,24 @@ Maps to **kerf Hard Rule 2** — the keyed reconciler matches items by `id` firs
 ## ❌ Incorrect
 
 ```tsx
-each(items, (item) => <li>{item.name}</li>)
+each(items, (item) => <li>{item.name}</li>);
 
 each(items, (item) => {
   return <li class="row">{item.name}</li>;
-})
+});
 
-each(items, (item) => <>{item.name}</>)
+each(items, (item) => <>{item.name}</>);
 ```
 
 ## ✅ Correct
 
 ```tsx
-each(items, (item) => <li data-key={item.id}>{item.name}</li>)
+each(items, (item) => <li data-key={item.id}>{item.name}</li>);
 
-each(items, (item) => <li id={item.id}>{item.name}</li>)
+each(items, (item) => <li id={item.id}>{item.name}</li>);
 
 // Spread attributes are conservatively allowed — they may include the key.
-each(items, (item) => <li {...item.attrs}>{item.name}</li>)
+each(items, (item) => <li {...item.attrs}>{item.name}</li>);
 ```
 
 ## What this rule does NOT catch

package/docs/rules/require-delegate-disposer.md

@@ -2,7 +2,7 @@
 
 Require capturing the disposer returned by `delegate()` and `delegateCapture()`.
 
-Both helpers install a single listener on the root element and return a `() => void` disposer — the *only* way to remove the listener once it's attached. Discarding the return value is safe in exactly one case: the registration is genuinely page-lifetime (root is `document.body` or another never-torn-down element, attached once at startup, never re-registered). In every other case the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state) — so an undisposed delegate on a transient root leaks both the listener and the app graph it references, and re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you.
+Both helpers install a single listener on the root element and return a `() => void` disposer — the _only_ way to remove the listener once it's attached. Discarding the return value is safe in exactly one case: the registration is genuinely page-lifetime (root is `document.body` or another never-torn-down element, attached once at startup, never re-registered). In every other case the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state) — so an undisposed delegate on a transient root leaks both the listener and the app graph it references, and re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you.
 
 See [kerf docs §5.3 — Disposers](https://brianwestphal.github.io/kerf/docs/5-event-delegation/#53-disposers) for the full rationale.
 
@@ -49,8 +49,8 @@ Or collect into a disposer array:
 ```ts
 const disposers: Array<() => void> = [];
 disposers.push(mount(host, render));
-disposers.push(delegate(host, 'click', '[data-action]', onAction));
-disposers.push(delegate(host, 'keydown', '[data-edit]', onEdit));
+disposers.push(delegate(host, "click", "[data-action]", onAction));
+disposers.push(delegate(host, "keydown", "[data-edit]", onEdit));
 
 function teardown() {
   for (const off of disposers) off();
@@ -64,13 +64,18 @@ If the registration is attached once at module load and the root never tears dow
 
 ```ts
 // 1. The `void` operator as an explicit-discard sigil.
-void delegate(document.body, 'click', ACTIONS.inc.selector, () => count.value++);
+void delegate(
+  document.body,
+  "click",
+  ACTIONS.inc.selector,
+  () => count.value++,
+);
 ```
 
 ```ts
 // 2. Standard eslint-disable for one-off cases.
 // eslint-disable-next-line kerfjs/require-delegate-disposer
-delegate(document.body, 'click', ACTIONS.inc.selector, () => count.value++);
+delegate(document.body, "click", ACTIONS.inc.selector, () => count.value++);
 ```
 
 `void` is the lower-friction option when the file has many page-lifetime registrations clustered together; eslint-disable carries the rule name with it, which makes it easier to grep for.

package/docs/rules/ui-composition.md

@@ -0,0 +1,5 @@
+# `ui-composition`
+
+Enforces composition facts published by the versioned UI catalog. `KUI-L201` reports a catalog component under a known, disallowed direct parent. `KUI-L202` reports a statically visible zone child—including an intrinsic or unknown JSX element—that is not one of the zone's cataloged `accepts` entries. `KUI-L203` reports a statically provable zone cardinality violation. Toolbar's `leading`, `center`, and `trailing` validation is therefore derived from its catalog entry rather than a duplicated rule-local allowlist.
+
+The parent check is intentionally conservative: it reports only when both child and direct parent resolve to cataloged imports. The Toolbar zone check understands fragments, arrays, and conditional/logical branches, but expressions whose content cannot be resolved statically remain runtime and accessibility work. Other catalog zone ids are not assumed to be JSX prop names. No autofix is offered because wrapping or moving UI changes structure and behavior.

package/docs/rules/ui-preferences.md

@@ -0,0 +1,5 @@
+# `ui-preferences`
+
+Reports cataloged components listed in an application UI profile preference's `avoid` set and points to the package-qualified `preferred` component. The stable diagnostic is `KUI-L301`.
+
+`recommended-ui` treats the rule as a warning; `strict-ui` treats it as an error. Use a narrowly targeted `KUI-L301` profile exception when a documented application boundary cannot follow the preference. Component substitutions are not autofixed because their props and interaction contracts can differ.

package/docs/rules/ui-public-boundaries.md

@@ -0,0 +1,7 @@
+# `ui-public-boundaries`
+
+Rejects `kui-*` classes and `--kui-*` custom properties that are not listed in the versioned composition catalog. This keeps application code out of private component anatomy while allowing cataloged styling seams.
+
+Diagnostics are stable: `KUI-L101` identifies a private/unknown class and `KUI-L102` an unknown token. Exact profile exceptions can name either id. The rule deliberately does not rewrite selectors or tokens because there is no generally safe replacement.
+
+The rule reads `@kerfjs/ui/ai/component-catalog-v2.json` by default. See the plugin README for alternate catalog settings used by monorepos and package authors.

package/docs/rules/ui-wiring.md

@@ -0,0 +1,5 @@
+# `ui-wiring`
+
+Checks wiring obligations published by the versioned composition catalog. `KUI-L401` reports a used component whose required helper or side-effect registration import is absent. `KUI-L402` reports a helper call whose disposer is discarded.
+
+Assign, return, or otherwise retain a disposer when the binding has a shorter lifetime than the page. A `void` call is accepted as an explicit page-lifetime choice. The rule derives valid helper sources from each v1 entry's `publicExports` and `wiring[].import` facts, so aliases, root named imports, root namespaces, wiring-subpath named imports, and wiring-subpath namespaces resolve without a second hard-coded export table. It does not attempt flow-sensitive cleanup proof and offers no autofix.

package/index.js

@@ -6,9 +6,13 @@ import preferAttrSelector from './lib/rules/prefer-attr-selector.js';
 import preferModuleJsxAugmentation from './lib/rules/prefer-module-jsx-augmentation.js';
 import requireDataKeyInEach from './lib/rules/require-data-key-in-each.js';
 import requireDelegateDisposer from './lib/rules/require-delegate-disposer.js';
+import uiComposition from './lib/rules/ui-composition.js';
+import uiPreferences from './lib/rules/ui-preferences.js';
+import uiPublicBoundaries from './lib/rules/ui-public-boundaries.js';
+import uiWiring from './lib/rules/ui-wiring.js';
 
 const plugin = {
-  meta: { name: 'eslint-plugin-kerfjs', version: '0.13.0' },
+  meta: { name: 'eslint-plugin-kerfjs', version: '4.5.0-beta.1' },
   rules: {
     'no-inline-jsx-event-handlers': noInlineJsxEventHandlers,
     'no-raw-with-dynamic-arg': noRawWithDynamicArg,
@@ -18,6 +22,10 @@ const plugin = {
     'prefer-module-jsx-augmentation': preferModuleJsxAugmentation,
     'prefer-attr-selector': preferAttrSelector,
     'ai-assistant-configs': aiAssistantConfigs,
+    'ui-composition': uiComposition,
+    'ui-preferences': uiPreferences,
+    'ui-public-boundaries': uiPublicBoundaries,
+    'ui-wiring': uiWiring,
   },
   configs: {},
 };
@@ -50,6 +58,25 @@ plugin.configs.recommended = {
   plugins: { kerfjs: plugin },
   rules: recommendedRules,
 };
+const recommendedUiRules = {
+  ...recommendedRules,
+  'kerfjs/ui-public-boundaries': 'error',
+  'kerfjs/ui-composition': 'error',
+  'kerfjs/ui-preferences': 'warn',
+  'kerfjs/ui-wiring': 'warn',
+};
+plugin.configs['recommended-ui'] = {
+  plugins: { kerfjs: plugin },
+  rules: recommendedUiRules,
+};
+plugin.configs['strict-ui'] = {
+  plugins: { kerfjs: plugin },
+  rules: {
+    ...recommendedUiRules,
+    'kerfjs/ui-preferences': 'error',
+    'kerfjs/ui-wiring': 'error',
+  },
+};
 plugin.configs.all = plugin.configs.recommended;
 
 // Legacy `.eslintrc` config — consumers extend `'plugin:kerfjs/legacy-recommended'`.

package/lib/rules/ai-assistant-configs.js

@@ -8,9 +8,10 @@
  * `KERF-APP-CANONICAL-END` marker; the consumer's append zone below the
  * marker is preserved byte-for-byte (the "option 2" strategy from KF-217).
  *
- * Unusual for an ESLint rule: the `fix()` callback writes to a file
- * OTHER than the linted source. ESLint only invokes `fix()` when
- * `--fix` is enabled, so the side effect is opt-in by definition.
+ * Unusual for an ESLint rule: the `fix()` callback writes to a file OTHER than
+ * the linted source. ESLint evaluates fix callbacks during ordinary lint too,
+ * so the callback must explicitly gate that side effect on the CLI's `--fix`
+ * flag.
  */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -105,8 +106,10 @@ export function classifyFile(file, bundleDir, cwd) {
   }
 
   const markerIdx = findMarkerIndex(consumer);
-  if (markerIdx === -1) return { state: 'forked', reason: 'no canonical-end marker' };
-  if (markerIdx === -2) return { state: 'forked', reason: 'multiple canonical-end markers' };
+  if (markerIdx === -1)
+    return { state: 'forked', reason: 'no canonical-end marker' };
+  if (markerIdx === -2)
+    return { state: 'forked', reason: 'multiple canonical-end markers' };
 
   const canonicalEnd = canonicalEndOffset(consumer);
   const consumerCanonical = consumer.slice(0, canonicalEnd);
@@ -118,12 +121,26 @@ export function classifyFile(file, bundleDir, cwd) {
   }
 
   const cmp = compareSemver(consumerVersion, file.version);
+  const consumerCanonicalHash = sha256(consumerCanonical);
   if (cmp === 0) {
     // Same version. Above-marker section should match the bundled sha256.
-    if (sha256(consumerCanonical) === file.sha256) return { state: 'ok' };
+    if (consumerCanonicalHash === file.sha256) return { state: 'ok' };
     return { state: 'forked', reason: 'content above marker has been edited' };
   }
   if (cmp < 0) {
+    const historicalHash = file.history?.[consumerVersion];
+    if (!historicalHash) {
+      return {
+        state: 'forked',
+        reason: `canonical hash for version ${consumerVersion} is unavailable`,
+      };
+    }
+    if (consumerCanonicalHash !== historicalHash) {
+      return {
+        state: 'forked',
+        reason: 'content above marker has been edited',
+      };
+    }
     return {
       state: 'stale',
       consumerVersion,
@@ -152,7 +169,9 @@ function loadBundle(cwd) {
 function isTriggered(name, cwd) {
   if (name === 'skill') return existsSync(join(cwd, '.claude'));
   if (name === 'cursorrules') {
-    return existsSync(join(cwd, '.cursorrules')) || existsSync(join(cwd, '.cursor'));
+    return (
+      existsSync(join(cwd, '.cursorrules')) || existsSync(join(cwd, '.cursor'))
+    );
   }
   return false;
 }
@@ -208,11 +227,11 @@ const meta = {
     stale:
       '{{tool}} drop-in at `{{dest}}` is stale (have {{consumerVersion}}, latest is {{bundledVersion}}). Run `eslint --fix` to update the canonical section above the `KERF-APP-CANONICAL-END` marker; your customizations below the marker are preserved.',
     forked:
-      '{{tool}} drop-in at `{{dest}}` is forked: {{reason}}. Restore the canonical layout (one `KERF-APP-CANONICAL-END` marker, no edits above it) or disable this rule with `\'kerfjs/ai-assistant-configs\': \'off\'`.',
+      "{{tool}} drop-in at `{{dest}}` is forked: {{reason}}. Restore the canonical layout (one `KERF-APP-CANONICAL-END` marker, no edits above it) or disable this rule with `'kerfjs/ai-assistant-configs': 'off'`.",
   },
-  // Mark as fixable so ESLint runs the `fix()` callback under `--fix`.
-  // The callback writes to a separate file and returns null, so ESLint
-  // applies no edit to the linted source itself — see file header.
+  // Mark as fixable so the CLI exposes this rule under `--fix`. The callback
+  // writes to a separate file and returns null, so ESLint applies no edit to
+  // the linted source itself — see file header.
   fixable: 'code',
 };
 
@@ -225,10 +244,7 @@ function create(context) {
       const claudeEnabled = options.claude !== false;
       const cursorEnabled = options.cursor !== false;
       // ESLint v9: `context.cwd` is a string. ESLint v8: `context.getCwd()`.
-      const cwd =
-        (typeof context.cwd === 'string' && context.cwd)
-        || (typeof context.getCwd === 'function' && context.getCwd())
-        || process.cwd();
+      const cwd = contextCwd(context);
       const checked = runCheck(cwd);
       CACHED_RESULT = checked;
       if (!checked) return;
@@ -238,7 +254,10 @@ function create(context) {
         if (file.name === 'cursorrules' && !cursorEnabled) continue;
         if (result.state === 'ok') continue;
 
-        const tool = file.name === 'skill' ? 'Claude Code kerf-app skill' : 'Cursor kerf rules';
+        const tool =
+          file.name === 'skill'
+            ? 'Claude Code kerf-app skill'
+            : 'Cursor kerf rules';
         const bundle = file.bundle; // e.g. 'ai/skill.md'
         const data = { tool, dest: file.dest, bundle };
 
@@ -248,7 +267,7 @@ function create(context) {
             messageId: 'missing',
             data,
             fix() {
-              applyFix(file, checked.bundleDir, cwd, '');
+              if (isFixCliRun()) applyFix(file, checked.bundleDir, cwd, '');
               return null;
             },
           });
@@ -262,7 +281,9 @@ function create(context) {
               bundledVersion: result.bundledVersion,
             },
             fix() {
-              applyFix(file, checked.bundleDir, cwd, result.appendZone);
+              if (isFixCliRun()) {
+                applyFix(file, checked.bundleDir, cwd, result.appendZone);
+              }
               return null;
             },
           });
@@ -278,4 +299,16 @@ function create(context) {
   };
 }
 
+function contextCwd(context) {
+  return (
+    (typeof context.cwd === 'string' && context.cwd) ||
+    (typeof context.getCwd === 'function' && context.getCwd()) ||
+    process.cwd()
+  );
+}
+
+function isFixCliRun() {
+  return process.argv.includes('--fix');
+}
+
 export default { meta, create };

package/lib/rules/no-inline-jsx-event-handlers.js

@@ -7,7 +7,7 @@ const meta = {
   type: 'problem',
   docs: {
     description:
-      "Disallow inline `onClick`-style JSX event handler attributes; use `data-action` + `delegate()` instead.",
+      'Disallow inline `onClick`-style JSX event handler attributes; use `data-action` + `delegate()` instead.',
     url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/no-inline-jsx-event-handlers.md',
   },
   schema: [],

package/lib/rules/no-nested-mount.js

@@ -34,7 +34,8 @@ function create(context) {
       let p = node.parent;
       while (p) {
         if (
-          (p.type === 'ArrowFunctionExpression' || p.type === 'FunctionExpression') &&
+          (p.type === 'ArrowFunctionExpression' ||
+            p.type === 'FunctionExpression') &&
           isMountCall(p.parent) &&
           p.parent.arguments.includes(p)
         ) {